当前位置： 首页 > news >正文

Swagger2 自定义排序

news 2026/5/12 3:41:20

分享一下Spring+Swagger2在线文档自定义排序的代码。

这里参考swagger2 接口排序_swagger接口排序-CSDN博客提供的思路，并在此基础上做了优化。

1、引用pom信息

<!--swagger依赖(pojo注解)--> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.20</version> </dependency> <!--生成后端开发文档--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> <exclusions> <exclusion> <artifactId>jackson-annotations</artifactId> <groupId>com.fasterxml.jackson.core</groupId> </exclusion> </exclusions> </dependency> <!--第三方生成后端开发文档页面UI--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> </dependency>

2、未排序效果

现有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(); Map<String, Object> data = new HashMap<String, 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(); Map<String, Object> data = new HashMap<String, 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(); Map<String, Object> data = new HashMap<String, 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并继承ServiceModelToSwagger2MapperImpl

API模块的排序，使用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 Map<String, Path> mapApiListings(Multimap<String, ApiListing> apiListings) { Map<String, Path> paths = Maps.newTreeMap(); Iterator var3 = apiListings.values().iterator(); while (var3.hasNext()) { ApiListing each = (ApiListing) var3.next(); List<ApiDescription> 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 = "0"+position; } paths.put(position + "-" + api.getPath(), this.mapOperations(api, Optional.fromNullable(paths.get(api.getPath())))); } } Map<String, 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, Optional<Path> 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 = "0"+position; } operation.setOperationId(position + from.getUniqueId()); operation.setResponses(this.mapResponseMessages(from.getResponseMessages())); operation.setSchemes(this.stringSetToSchemeList(from.getProtocol())); Set<String> set = from.getTags(); if (set != null) { Iterator<String> it= set.iterator(); Set<String> 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()); Set<String> set1 = from.getConsumes(); if (set1 != null) { operation.setConsumes(new ArrayList(set1)); } else { operation.setConsumes((List) null); } Set<String> 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 List<Tag> tagSetToTagList(Set<springfox.documentation.service.Tag> set) { List<Tag> tlist = super.tagSetToTagList(set); Collections.sort(tlist, new Comparator<Tag>() { @Override public int compare(Tag t1, Tag t2) { return t1.getName().compareTo(t2.getName()); } }); List<Tag> result = new LinkedList<>(); Iterator<Tag> 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(); Map<String, Object> data = new HashMap<String, 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(); Map<String, Object> data = new HashMap<String, 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(); Map<String, Object> data = new HashMap<String, 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显示如下：

http://www.jsqmd.com/news/491400/

相关文章：

  • UE 树形图 C++版
  • 广柔扁平排线电缆在人形机器人应用优势探讨
  • Win+安装Ollama+本地Deepseek-R1+Cherrystudio使用
  • 2026年建筑加固优选：碳纤维布厂家加固博士，以50年质保定义安全新标准 - 速递信息
  • 探索C语言中数组 sizeof 、 strlen 的奥秘
  • UE 最全FString字符串与各格式转换 输出
  • 2026大专财富管理毕业工资多少？就业薪资、岗位方向与升职考证全攻略
  • “安、迅、智、省”四维发力，高频科技解锁半导体超纯水运维新价值
  • 基于 FastAPI + Vue 3 深度定制的全栈自动化执行引擎设计全解
  • whois社区贡献指南：如何提交解析器与参与开源开发
  • 一种在winfrom窗体中显示计算公式的解决方案
  • 电源动态响应测试
  • MobileCoin智能合约开发入门：构建基于隐私支付的去中心化应用
  • GARbro：视觉小说资源浏览器
  • 2026年智能客服哪家好？AI客服机器人与系统选购指南 - 品牌2026
  • Pleaserun vs 手动编写init脚本：效率提升10倍的秘密
  • 2026高职物联网毕业起薪一般多少？就业方向、岗位薪资与升职路径全解析
  • 2026年角钢厂家怎么选？柒鑫合以工字钢、槽钢、角钢为核心，构建全品类型钢供应能力 - 深度智识库
  • MoonShine Admin Panel完全解析：为何它是2024年最值得尝试的Laravel后台框架？
  • OpenClaw技术详解：原理、使用方法、应用场景与架构设计
  • laravel-menu性能优化：高效生成与缓存策略
  • 2026高端全屋智能家居品牌推荐排行 权威评测 全场景AI/家居一体化 - 极欧测评
  • PHing配置文件完全手册：build.xml编写指南与示例
  • go-face完全指南：用Go语言构建高性能人脸识别系统的终极教程
  • 2026 年云南大棚管实力厂家合集 本地口碑出众的钢材服务商盘点 - 深度智识库
  • 对比实验：VoiceprintRecognition-Pytorch中8种损失函数的性能差异
  • 2026年靠谱智能客服系统盘点，适合企业使用的客服工具推荐 - 品牌2026
  • 综述自免疾病中的关键生物标志物研究，解密自身免疫性疾病的“预警密码”
  • 银泰百货卡变现指南：这些平台真的值得信赖吗？ - 团团收购物卡回收
  • MobileCoin与传统支付对比：为什么隐私支付是未来移动金融的必然趋势