Spring Boot集成Swagger接口分类与各元素排序问题

最新推荐文章于 2024-05-08 00:22:21 发布
最新推荐文章于 2024-05-08 00:22:21 发布
阅读量2.1k 收藏 1
点赞数
分类专栏： # Spring 文章标签： spring boot 后端 java
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_45922256/article/details/134032551
版权

在上一篇中我们完成使用JSR-303校验，以及利用Swagger2得到相关接口文档，这节，我们在原先的基础之上，完成Swagger中关于对各个元素之间控制前后顺序的具体配置方法。

Swagger的接口的分组

首先我们需要对Swagger中的接口也就是以Controller 层作为第一级梯度进行组织的，Controller在我们实际开发中，与其他具体接口之间是存在一对多的关系，我们可以将同属一个模块的接口定义在一个Controller 中，默认情况之下，我们的Swagger 是以Controller为单位，对接口进行分组管理，在Swagger 中，这个分组的元素被称为Tag,但是这里的Tag与接口的关系并不是一对多关系，它支持更加丰富的多对多的关系，

默认的分组

首先通过创建一个简单的例子进，来看一下，我们是如何处理Swagger是如如何根据Controller来组织Tag与接口关系的，定义两个Controller，分别负责教师管理与学生管理接口，为了重复利用代码，我们就在上一篇的基础之上进行代码添加了：
为了简单明了，我均将下列代码放在Application类里边

@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    @GetMapping("/miaow")
    public String miaow() {
        return "miaow";
    }
}

@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation("获取学生清单")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    @ApiOperation("获取教某个学生的老师清单")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }

    @ApiOperation("创建一个学生")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }
}

此时通过：localhost:8080/swagger-ui.html 访问得到我们Swagger的组织结构是

在这里插入图片描述
在上图中我们了解到我们定义的控制层，得到的swagger生成的默认结构展示出来了。

application.properties文件

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.9.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=miaow
swagger.contact.url=https://luoxiaohei520.github.io
swagger.contact.email=miaow@qq.com
swagger.base-package=com.didispace
swagger.base-path=/**

swagger.ui-config.tags-sorter=alpha
swagger.ui-config.operations-sorter=alpha

在启动类添加相关控制层接口：

@EnableSwagger2Doc
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
       SpringApplication.run(Application.class, args);
    }

    @Api(tags = {"1-教师管理","3-教学管理"})
    @RestController
    @RequestMapping(value = "/teacher")
    static class TeacherController {
        @ApiOperation(value = "miaow")
        @GetMapping("/miaow")
        public String miaow() {
            return "miaow";
        }
    }
    
    @Api(tags = {"2-学生管理"})
    @RestController
    @RequestMapping(value = "/student")
    static class StudentController {
        @ApiOperation(value = "获取学生清单", tags = "3-教学管理")
        @GetMapping("/list")
        public String bbb() {
            return "bbb";
        }
        @ApiOperation("获取教某个学生的老师清单")
        @GetMapping("/his-teachers")
        public String ccc() {
            return "ccc";
        }
        @ApiOperation("创建一个学生")
        @PostMapping("/aaa")
        public String aaa() {
            return "aaa";
        }
    }
}

得到结果集
在这里插入图片描述

自定义默认分组的名称

@Api(tags = "教师管理")
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
    // ...
}

@Api(tags = "学生管理")
@RestController
@RequestMapping(value = "/student")
static class StudentController {
    // ...
}

我们在Api的tags修改成为我们想要的表达文字：
在这里插入图片描述

合并Controller分组

在此，我们使用了Tag和Controller 一一对应的情况，Swagger中还支持更加灵活的分组！从@Api注解中，我们如果有去看详细代码的时候，发现tags属性其实是一个数组类型。

在这里插入图片描述
因而，我们可以通过地定义同名的Tag来汇总Controller中的相关接口，比如我们可以定义一个Tag为“教学管理“，让这个分组同时包含教师管理和学生管理的所有接口，案例如下：

@Api(tags = {"教师管理", "教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
    // ...
}

@Api(tags = {"学生管理", "教学管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
    // ...
}

更新细粒度的接口分组

通过@Api可以实现将Controller中的接口合并到一个Tag中,但是如果我们希望精确到某个接口的合并，我们应该如何做?

@Api(tags = {"教师管理","教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    @ApiOperation(value = "maiow")
    @GetMapping("/miaow")
    public String miaow() {
        return "miaow";
    }

}

@Api(tags = {"学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation(value = "获取学生清单", tags = "教学管理")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    @ApiOperation("获取教某个学生的老师清单")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }

    @ApiOperation("创建一个学生")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }

}

得到效果图：
在这里插入图片描述

内容的顺序

在完成了接口的分组后，我们可以进行对接口内容的展示顺序进行调整，其中，我们主要涉及三个方面：分组的排序、接口的排序、以及参数的排序。

分组排序

关于分组排序，也就是Tag的排序。目前版本的Swagger支持并不太好，通过文档我们可以找到关于Tag排序的配置方法。

第一种，适合原生的Swagger用户，修改：
在这里插入图片描述
第二种方式：Swagger Starter用户，可以通过修改配置的方式：

swagger.ui-config.tags-sorter=alpha

修改上述的配置的源码：

public enum TagsSorter {
  ALPHA("alpha");

  private final String value;

  TagsSorter(String value) {
    this.value = value;
  }

  @JsonValue
  public String getValue() {
    return value;
  }

  public static TagsSorter of(String name) {
    for (TagsSorter tagsSorter : TagsSorter.values()) {
      if (tagsSorter.value.equals(name)) {
        return tagsSorter;
      }
    }
    return null;
  }
}

我们可以发现Swagger 提供考虑一个选项，就是按照字字母顺序进行排序。

@Api(tags = {"1-教师管理","3-教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = {"2-学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    @ApiOperation(value = "获取学生清单", tags = "3-教学管理")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }
    // ...
}

在这里插入图片描述

接口的排序

在完成了分组排序问题（虽然不太优雅…）之后，在来看看同一分组内各个接口该如何实现排序。同样的，凡事先查文档，可以看到Swagger也提供了相应的配置，下面也分两种配置方式介绍：
第一种还是适合原生Swagger用户的，可以修改：
在这里插入图片描述
第二种：Swagger Starter用户，可以通过修改配置方式：

swagger.ui-config.operations-sorter=alpha

这个配置不像Tag的排序配置没有可选项。它提供了两个配置项：alpha和method，分别代表了按字母表排序以及按方法定义顺序排序。当我们不配置的时候，改配置默认为alpha。

在这里插入图片描述

参数的排序

完成了接口的排序后，更加细粒度的就是请求参数的排序了，在默认的情况下，我们的Swagger会对Model的参数内容展示进行按照字母排序，我们的展示的User在Swagger之前是这样的：

现在，我们希望可以按照Model中定义的成员变量顺序来展示，那么需要我们通过@ApiModelProperty 注解的position参数来实现位置的设置。

对应的User对象如下：
在这里插入图片描述
w未加

@ApiModel(description = "用户实体")
public class User {

    @ApiModelProperty(value = "用户编号", position = 1)
    private Long id;

    @NotNull
    @Size(min = 2, max = 5)
    @ApiModelProperty(value = "用户姓名", position = 2)
    private String name;

    @NotNull
    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用户年龄", position = 3)
    private Integer age;

    @NotNull
    @Email
    @ApiModelProperty(value = "用户邮箱", position = 4)
    private String email;


    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public User(Long id, String name, Integer age, String email) {
        this.id = id;
        this.name = name;
        this.age = age;
        this.email = email;
    }

    public User() {
    }
}

加了Position之后的swagger展示：
在这里插入图片描述

Miaow.Y.Hu
关注
  • 0
    点赞
  • 踩
  • 1
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
专栏目录
Spring Boot 2.x基础教程：Swagger接口分类与各元素排序问题详解
程序猿DD
10-09 949
点击蓝色“程序猿DD”关注我回复“资源”获取独家整理的学习资料！作者 | 翟永超来源 |didispace.com/spring-boot-learning-21-2-...
Swagger2为接口进行排序
m0_54096780的博客
10-08 3236
声明！声明！声明！如果没有做其他配置的话，按照下方的配置肯定可以用，但是如果有其他配置的话我就不敢保证了，Swagger迭代的挺快的，不同版本之间的配置也略有不同。 第一步：引入依赖 注意：直接复制，不要修改版本 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version&gt
swagger2 接口排序
jinhf10的博客
12-24 1万+
最近在使用swagger2作用在线文档工具，完成后发现在页面上模块和接口的顺序是混乱的。 swagger使用的版本信息 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2&l...
Swagger——【SpringBoot集成Swagger、配置Swagger、配置扫描接口、配置API分组】
最新发布
2301_76238237的博客
05-08 361
自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。深知大多数Java工程师，想要提升技能，往往是自己摸索成长，自己不成体系的自学效果低效漫长且无助。因此收集整理了一份《2024年Java开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。
Swagger 接口分组
_修铁路的、的博客
03-17 9188
Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 default 分组下，如果功能模块和接口数量一多，就会显得有些凌乱，不方便查找和使用。 为了解决这个问题，今天上午花了些时间查找Swagger 的接口分组设置办法，由于一开始思路和关键字设置不准备等原因，一时没找到正确满意的解决方案，直至看到大佬博客《swagger多个分...
knife4j、swagger、springdoc 返回接口分组排序问题
Stronger的博客
05-31 5690
解决knife4j返回接口分组排序问题
Spring Boot集成 Swagger2 展现在线接口文档
06-03
Spring Boot 集成 Swagger2 展现在线接口文档 Spring Boot 是一个基于 Java 的框架，用于快速构建生产级别的应用程序。Swagger 是一个流行的 API 文档工具，能够生成在线接口文档，帮助开发人员和调用接口的人员更...
Spring boot集成swagger2生成接口文档的全过程
08-25
主要给大家介绍了关于Spring boot集成swagger2生成接口文档的相关资料，文中通过示例代码介绍的非常详细，对大家学习或者使用Spring boot具有一定的参考学习价值，需要的朋友们下面来一起学习学习吧
Spring Boot集成Swagger2项目实战
08-28
在日常的工作中，我们往往需要给前端（WEB端、IOS、Android）或者第三方提供接口，这个时候我们就需要给他们提供一份详细的API说明文档。这篇文章我们就来分享一种API文档维护的方式，即通过Swagger来自动生成...
Spring Boot 2.7.5 集成 Swagger 3
11-22
Spring Boot 2.7.5 集成 Swagger 3，用于前后端分离开发，前端需要经常查看后端接口定义，以及接口的响应，所以集成可视化、交互式的 api 文档至关重要。此外还可以测试后端接口。
Spring Boot集成Swagger使用指南.pdf
05-12
文档为使用Spring Boot集成Swagger使用指南，主要包括swagger的组成，集成过程，以及常用注解的解释，通过文档应该可以使用swagger展示自己撰写的REST接口，进而更好的进行前后端交互。
swagger分组
weixin_42336453的博客
09-11 154
swagger
Swagger @ApiModelProperty注解 默认按照代码中字段定义的顺序排序
qq_40518157的博客
06-16 1113
【代码】Swagger @ApiModelProperty注解 默认按照代码中字段定义的顺序排序。
springboot集成swagger入门
klz
02-20 2182
springboot集成swagger入门 官网 官网： http://petstore.swagger.io/ 导入依赖 swagger2依赖 + springfox-swagger-ui依赖 或者 swagger-bootstrap-ui依赖 或者2个都加 <dependency> <groupId>io.springfox</g...
Swagger接口动态分组
csdndemimang的博客
11-01 1288
前言:网上查的接口分组,都是手动配置多个Docket来实现分组,但是这样每加一个业务还要改这里代码,太麻烦所以自己改造了一下,代码效果如下 注意:这种方式要保证接口要有一定的规则,比如(有如下三个接口1.aaa/xxx/xxx, 2.aaa/bbb/bbb,3.ccc/xx/bb)那么就会有aaa和ccc两个分组 代码: import org.springframework.beans.factory.support.DefaultListableBeanFactory; import org.sp
spring+swagger排序说明
weixin_42165041的博客
12-12 1万+
所用版本： swagger版本信息 &lt;!--swagger本身不支持spring mvc的，springfox把swagger包装了一下，让他可以支持springmvc --&gt; &lt;dependency&gt; &lt;groupId&gt;io.springfox&lt;/groupId&gt; &lt;artifactId&gt;springfox-swa...
Swagger2 进行分组
热门推荐
qq_41973154的博客
04-23 1万+
Swagger是一个很好的api文档，如果我们的接口过于多，那么一个页面很难展示，查找不方便，那么我们就对swagger进行分组。 分组策略为按包名称分组，另一个是按请求路径进行分类。 @Configuration @EnableSwagger2 public class SwaggerConfiguration { //设置显示状态，value是在pom中配置的 @Value("${mein...
Swagger @Api position失效，解决解决接口排序问题（最简单版）
DL_jianglin的博客
05-19 4100
我在网上看了很多版本关于如何解决这个问题，但是都很复杂，现在提供一个最简单的方式 Swagger依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> &lt
spring boot 集成swagger3
10-16
好的，关于集成Swagger3，你可以按照以下步骤进行操作： 1. 在pom.xml文件中添加Swagger3的依赖： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 2. 在Spring Boot的启动类上添加`@EnableSwagger2`注解： ```java @SpringBootApplication @EnableSwagger2 public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } } ``` 3. 创建Swagger配置类，配置Swagger相关信息： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot集成Swagger3") .description("Spring Boot集成Swagger3示例") .version("1.0") .build(); } } ``` 4. 启动应用程序，访问`http://localhost:8080/swagger-ui/index.html`即可查看API文档。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

Miaow.Y.Hu

赏一口饭吃吧，大大们

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值