Swagger2 自定义排序

分享一下SpringSwagger2在线文档自定义排序的代码。这里参考swagger2 接口排序_swagger接口排序-CSDN博客提供的思路并在此基础上做了优化。1、引用pom信息!--swagger依赖(pojo注解)-- dependency groupIdio.swagger/groupId artifactIdswagger-annotations/artifactId version1.5.20/version /dependency !--生成后端开发文档-- dependency groupIdio.springfox/groupId artifactIdspringfox-swagger2/artifactId version2.7.0/version exclusions exclusion artifactIdjackson-annotations/artifactId groupIdcom.fasterxml.jackson.core/groupId /exclusion /exclusions /dependency !--第三方生成后端开发文档页面UI-- dependency groupIdcom.github.xiaoymin/groupId artifactIdswagger-bootstrap-ui/artifactId version1.9.6/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /dependency2、未排序效果现有3个接口模块Api(tags 用户用户相关接口) RestController RequestMapping(/system/user) public class UserController{ /** 列表 */ ApiOperation(value 列表, notes ) ApiImplicitParams({ ApiImplicitParam(name pageNum, value 页码, dataType int, paramType query), ApiImplicitParam(name pageSize, value 页面大小, dataType int, paramType query), ApiImplicitParam(name type, value 标签类型, dataType String, paramType query), ApiImplicitParam(name name, value 标签名称, dataType String, paramType query), ApiImplicitParam(name invalid, value 状态, dataType int, paramType query), }) PostMapping(/list) public ReturnMap list(Integer pageNum, Integer pageSize, String type, String name, Integer invalid, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); MapString, Object data new HashMapString, Object(); returnMap.setData(data); returnMap.success(); return returnMap; } ApiOperation(value 新增用户, notes ) ApiImplicitParams({ }) PostMapping(/addUser) public ReturnMap addUser(RequestBody User user, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); returnMap.success(); return returnMap; } }Api(tags 系统字典相关接口) RestController RequestMapping(/system/dict) public class DictController{ /** 列表 */ ApiOperation(value 列表, notes ) ApiImplicitParams({ ApiImplicitParam(name pageNum, value 页码, dataType int, paramType query), ApiImplicitParam(name pageSize, value 页面大小, dataType int, paramType query), ApiImplicitParam(name type, value 标签类型, dataType String, paramType query), ApiImplicitParam(name name, value 标签名称, dataType String, paramType query), ApiImplicitParam(name invalid, value 状态, dataType int, paramType query), }) PostMapping(/list) public ReturnMap list(Integer pageNum, Integer pageSize, String type, String name, Integer invalid, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); MapString, Object data new HashMapString, Object(); returnMap.setData(data); returnMap.success(); return returnMap; } //更新角色 ApiOperation(value 新增字典, notes ) ApiImplicitParams({ }) PostMapping(/addDict) public ReturnMap addDict(RequestBody Dict dict, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); returnMap.success(); return returnMap; } }Api(tags 系统字典类型相关接口) RestController RequestMapping(/system/dictType) public class DictTypeController{ /** 列表 */ ApiOperation(value 列表, notes ) ApiImplicitParams({ ApiImplicitParam(name pageNum, value 页码, dataType int, paramType query), ApiImplicitParam(name pageSize, value 页面大小, dataType int, paramType query), ApiImplicitParam(name type, value 标签类型, dataType String, paramType query), ApiImplicitParam(name name, value 标签名称, dataType String, paramType query), ApiImplicitParam(name invalid, value 状态, dataType int, paramType query), }) PostMapping(/list) public ReturnMap list(Integer pageNum, Integer pageSize, String type, String name, Integer invalid, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); MapString, Object data new HashMapString, Object(); returnMap.setData(data); returnMap.success(); return returnMap; } //新增角色 ApiOperation(value 新增字典类型, notes ) ApiImplicitParams({ }) PostMapping(/addDictType) public ReturnMap addDictType(RequestBody DictType dictType, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); returnMap.success(); return returnMap; } }Swagger2显示如下期望展示顺序如下3、自定义排序改造3.1 添加配置类Swagger2CustomSort并继承ServiceModelToSwagger2MapperImplAPI模块的排序使用tag名称排序在名称前加上前缀0X0X_##_即在名称就加上0101_##_、0102_##_、0201_##_、0202_##_。但为了页面展示效果在排序后把前缀进行处理。接口的排序使用ApiOperation的position实现。import com.google.common.base.Optional; import com.google.common.collect.Maps; import com.google.common.collect.Multimap; import io.swagger.models.Operation; import io.swagger.models.Path; import io.swagger.models.Tag; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Primary; import org.springframework.core.Ordered; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; import springfox.documentation.builders.BuilderDefaults; import springfox.documentation.service.ApiDescription; import springfox.documentation.service.ApiListing; import springfox.documentation.swagger2.mappers.ServiceModelToSwagger2MapperImpl; import springfox.documentation.swagger2.mappers.VendorExtensionsMapper; import java.util.*; /** * 自定义排序 * * 经过代码跟踪分析总结如下 * 1.API模块的排序是依据tag 的名称进行的虽然Api里保留有position属性但是已经完全弃用。 * 2.接口的排序也是依据ApiOperation里value的值进行的position属性虽然废弃但是仍可以进行设置取值。 * * 解决办法如下 * 1.API模块的排序使用tag名称排序在名称前加上前缀0X0X_##_即在名称就加上0101_##_、0102_##_、0201_##_、0202_##_。但为了页面展示效果在排序后把前缀进行处理; * 2.接口的排序使用ApiOperation的position实现。 * * author https://blog.csdn.net/jinhf10/article/details/103684895 */ Primary //同一个接口可能会有几种不同的实现类而默认只会采取其中一种的情况下 Component(ServiceModelToSwagger2Mapper) Order(Ordered.HIGHEST_PRECEDENCE) public class Swagger2CustomSort extends ServiceModelToSwagger2MapperImpl { //API接口排序序号识别 private static final String API_SORT_PREFIX _##_; Autowired private VendorExtensionsMapper vendorExtensionsMapper; protected MapString, Path mapApiListings(MultimapString, ApiListing apiListings) { MapString, Path paths Maps.newTreeMap(); Iterator var3 apiListings.values().iterator(); while (var3.hasNext()) { ApiListing each (ApiListing) var3.next(); ListApiDescription list each.getApis(); Iterator var5 each.getApis().iterator(); while (var5.hasNext()) { ApiDescription api (ApiDescription) var5.next(); String position api.getOperations().get(0).getPosition(); while(position.length() 32){ position 0position; } paths.put(position - api.getPath(), this.mapOperations(api, Optional.fromNullable(paths.get(api.getPath())))); } } MapString, Path paths2 new LinkedHashMap(); for (String key : paths.keySet()) { paths2.put(key.substring(key.indexOf(-) 1), paths.get(key)); } return paths2; } private Path mapOperations(ApiDescription api, OptionalPath existingPath) { Path path (Path) existingPath.or(new Path()); Iterator var4 BuilderDefaults.nullToEmptyList(api.getOperations()).iterator(); while (var4.hasNext()) { springfox.documentation.service.Operation each (springfox.documentation.service.Operation) var4.next(); Operation operation this.mapOperation(each); path.set(each.getMethod().toString().toLowerCase(), operation); } return path; } protected Operation mapOperation(springfox.documentation.service.Operation from) { if (from null) { return null; } else { Operation operation new Operation(); operation.setSecurity(this.mapAuthorizations(from.getSecurityReferences())); operation.setVendorExtensions(this.vendorExtensionsMapper.mapExtensions(from.getVendorExtensions())); operation.setDescription(from.getNotes()); String position from.getPosition(); while(position.length() 32){ position 0position; } operation.setOperationId(position from.getUniqueId()); operation.setResponses(this.mapResponseMessages(from.getResponseMessages())); operation.setSchemes(this.stringSetToSchemeList(from.getProtocol())); SetString set from.getTags(); if (set ! null) { IteratorString it set.iterator(); SetString rset new HashSet(); while (it.hasNext()){ String tagName it.next(); if(API_SORT_PREFIX!null !.equals(API_SORT_PREFIX)){ if(tagName!null !.equals(tagName) tagName.indexOf(API_SORT_PREFIX)0){ rset.add(tagName.substring(tagName.indexOf(API_SORT_PREFIX) API_SORT_PREFIX.length())); }else{ rset.add(tagName); } }else{ rset.add(tagName); } } operation.setTags(new ArrayList(rset)); } else { operation.setTags((List) null); } operation.setSummary(from.getSummary()); SetString set1 from.getConsumes(); if (set1 ! null) { operation.setConsumes(new ArrayList(set1)); } else { operation.setConsumes((List) null); } SetString set2 from.getProduces(); if (set2 ! null) { operation.setProduces(new ArrayList(set2)); } else { operation.setProduces((List) null); } operation.setParameters(this.parameterListToParameterList(from.getParameters())); if (from.getDeprecated() ! null) { operation.setDeprecated(Boolean.parseBoolean(from.getDeprecated())); } return operation; } } Override protected ListTag tagSetToTagList(Setspringfox.documentation.service.Tag set) { ListTag tlist super.tagSetToTagList(set); Collections.sort(tlist, new ComparatorTag() { Override public int compare(Tag t1, Tag t2) { return t1.getName().compareTo(t2.getName()); } }); ListTag result new LinkedList(); IteratorTag it tlist.iterator(); while (it.hasNext()) { Tag tag it.next(); Tag tt new Tag(); if(API_SORT_PREFIX!null !.equals(API_SORT_PREFIX)){ if(tag.getName()!null !.equals(tag.getName()) tag.getName().indexOf(API_SORT_PREFIX)0){ tt.setName(tag.getName().substring(tag.getName().indexOf(API_SORT_PREFIX) API_SORT_PREFIX.length())); }else{ tt.setName(tag.getName()); } }else{ tt.setName(tag.getName()); } tt.setDescription(tag.getDescription()); result.add(tt); } return result; } }3.2 接口Controller调整做如下调整具体代码如下Api(tags 00101_##_用户用户相关接口) RestController RequestMapping(/system/user) public class UserController{ /** 列表 */ ApiOperation(value 列表, notes , position 1) ApiImplicitParams({ ApiImplicitParam(name pageNum, value 页码, dataType int, paramType query), ApiImplicitParam(name pageSize, value 页面大小, dataType int, paramType query), ApiImplicitParam(name type, value 标签类型, dataType String, paramType query), ApiImplicitParam(name name, value 标签名称, dataType String, paramType query), ApiImplicitParam(name invalid, value 状态, dataType int, paramType query), }) PostMapping(/list) public ReturnMap list(Integer pageNum, Integer pageSize, String type, String name, Integer invalid, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); MapString, Object data new HashMapString, Object(); returnMap.setData(data); returnMap.success(); return returnMap; } ApiOperation(value 新增用户, notes , position 2) ApiImplicitParams({ }) PostMapping(/addUser) public ReturnMap addUser(RequestBody User user, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); returnMap.success(); return returnMap; } }Api(tags 00202_##_系统字典相关接口) RestController RequestMapping(/system/dict) public class DictController{ /** 列表 */ ApiOperation(value 列表, notes , position 1) ApiImplicitParams({ ApiImplicitParam(name pageNum, value 页码, dataType int, paramType query), ApiImplicitParam(name pageSize, value 页面大小, dataType int, paramType query), ApiImplicitParam(name type, value 标签类型, dataType String, paramType query), ApiImplicitParam(name name, value 标签名称, dataType String, paramType query), ApiImplicitParam(name invalid, value 状态, dataType int, paramType query), }) PostMapping(/list) public ReturnMap list(Integer pageNum, Integer pageSize, String type, String name, Integer invalid, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); MapString, Object data new HashMapString, Object(); returnMap.setData(data); returnMap.success(); return returnMap; } //更新角色 ApiOperation(value 新增字典, notes , position 2) ApiImplicitParams({ }) PostMapping(/addDict) public ReturnMap addDict(RequestBody Dict dict, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); returnMap.success(); return returnMap; } }Api(tags 00201_##_系统字典类型相关接口) RestController RequestMapping(/system/dictType) public class DictTypeController{ /** 列表 */ ApiOperation(value 列表, notes , position 1) ApiImplicitParams({ ApiImplicitParam(name pageNum, value 页码, dataType int, paramType query), ApiImplicitParam(name pageSize, value 页面大小, dataType int, paramType query), ApiImplicitParam(name type, value 标签类型, dataType String, paramType query), ApiImplicitParam(name name, value 标签名称, dataType String, paramType query), ApiImplicitParam(name invalid, value 状态, dataType int, paramType query), }) PostMapping(/list) public ReturnMap list(Integer pageNum, Integer pageSize, String type, String name, Integer invalid, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); MapString, Object data new HashMapString, Object(); returnMap.setData(data); returnMap.success(); return returnMap; } //新增角色 ApiOperation(value 新增字典类型, notes , position 2) ApiImplicitParams({ }) PostMapping(/addDictType) public ReturnMap addDictType(RequestBody DictType dictType, HttpServletRequest request, HttpServletResponse response){ ReturnMap returnMap new ReturnMap(); returnMap.success(); return returnMap; } }4、自定义排序效果重新编译运行后Swagger2显示如下