Spring Boot集成Swagger

最新推荐文章于 2024-08-30 10:35:49 发布

Breakthro

最新推荐文章于 2024-08-30 10:35:49 发布

阅读量677

点赞数 1

分类专栏： Spring Boot 文章标签： spring boot 后端 java

本文链接：https://blog.csdn.net/qq_45788135/article/details/132811256

版权

Spring Boot 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

一、集成Swagger与Springdoc

1、Swagger简介

Swagger是一套基于 OpenAPI（是一个组织（OpenAPI Initiative），他们制定了一个如何描述 HTTP API 的规范（OpenAPI Specification））规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

2、为什么要使用Swagger

当下很多公司都采用前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是由后端开发人员手动编写的，但是这种方式很难保证文档的及时性和完整性，并且还会加大我们沟通的成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，下面我们来了解一下它的优点：

代码变，文档变。只需要少量注解，Swagger 就会根据代码自动生成 API 文档，很好的保证了文档的时效性。
跨语言性。支持四十多种语言。
Swagger UI 呈现出来的是一份可交互是的API文档，我们可以直接在该页面进行API的调试工作，省去了准备复杂调用参数的过程。
还可以将文档规范导入相关的工具(例如SoapUI)，这些工具将会为我们创建自动化测试

3、基本使用

（1）导入相关依赖

        <!--TODO: Springdoc-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.7.0</version>
        </dependency>

注意：此处使用的Spring Boot版本为2.7.8，如果使用Spring Boot3及以上更高版本的，Springdoc也应使用更高版本的，导入的依赖如下：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

（2）编写api

@RestController
@RequestMapping("/user")
public class UserController {
    @PostMapping("/add")
    public boolean addUser(@RequestBody User user) {
        return false;
    }
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id) {
        return new User();
    }
    @PutMapping("/update")
    public boolean update(@RequestBody User user) {
        return true;
    }
    @DeleteMapping("/delete/{id}")
    public boolean delete(@PathVariable("id") int id) {
        return true;
    }
}

（3）访问与效果展示

通过输入http://ip:port/swagger-ui.html即可查看文档。如http://localhost:8080/swagger-ui.html

可以看到已经有了基本的接口展示列表，但是对于接口的信息描述还不是特别清楚，接下来我们通过一些高级配置，让这份文档变得更加易读。

（4）配置文档信息

Springdoc 提供了一个OpenAPI对象，我们可以通过这个对象来灵活地配置 Swagger 的各项属性，比如配置文档名称等，下面我们在 config 包下新建一个 SpringDocConfig 配置类：

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI myOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("程序员API")
                        .description("程序员的大本营")
                        .version("v1.0.0")
                        .license(new License()
                                .name("许可协议")
                                .url("https://blog.csdn.net/qq_45788135?spm=1000.2115.3001.5343"))
                        .contact(new Contact()
                                .name("RoronoaZoro")
                                .email("123@gmail.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("RoronoaZoro博客")
                        .url("https://blog.csdn.net/qq_45788135?spm=1000.2115.3001.5343"));
    }
 }

（5）配置文档分组和扫描接口

假如你有两类 controller，一类以 /user 为前缀，一类以 /admin 为前缀，就可以将其配置为两个分组。

很多时候我们只有一个分组，如果没有配置分组，默认是 default。

@Configuration
public class SpringDocConfig {
   ...
    @Bean
    public GroupedOpenApi publicApi() {
       return GroupedOpenApi.builder()
           .group("api")
           .displayName("api")
           .packagesToScan("com.ujcms.cms.core.web.api")
           .pathsToMatch("/api/**")
           .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
            .group("admin")
            .displayName("admin")
            .packagesToScan("com.ujcms.cms.core.web.admin")
            .pathsToMatch("/admin/**")
            .build();
    }
}

也可在配置文件中设置分组：

springdoc.group-configs:
  - group: api
    displayName: api
    packagesToScan: com.ujcms.cms.core.web.api
    pathsToMatch: /api/**
  - group: admin
    displayName: admin
    packagesToScan: com.ujcms.cms.core.web.admin
    pathsToMatch: /admin/**

设置完成后在SwaggerUI上可以通过右上角的下拉框选择要展示的 group，效果如下：

（6）常用注解

注解	含义
@Tag	用在控制器类上，描述此控制器的信息
@Operation	用在控制器类的方法里，描述此 api 的信息
@Parameter	用在控制器类的方法里的参数上，描述参数信息
@Parameters	用在控制器类的方法里的参数上
@Schema	用于实体类，以及实体类的属性上
@ApiResponse	用在控制器类的方法的返回值上
@ApiResponses	用在控制器类的方法的返回值上
@Hidden	用在各种地方，用于隐藏该 api

通过在 控制器类 上添加@Tag注解，可以给控制器增加标签和 描述信息。

@Tag(name = "用户相关接口", description = "提供用户相关的 Rest API")
public class UserController{
}

通过在 接口方法 上添加@Operation注解来展开对接口的描述，当然这个注解还可以指定很多内容。

@Operation("新增用户接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user) { 
    return false;
}

通过在 接口方法的参数列表里 添加 @Parameter注解来描述接口的参数信息：

@GetMapping("/{id}")
public User getUser(@Parameter(description = "用户id") @PathVariable Integer id) {
}

@Parameters与@Parameter作用一样，但是可以批量添加，不用一个一个的写在参数前面：

@Parameters(value = {
        @Parameter(name = "name", description = "姓名", in = ParameterIn.PATH),
        @Parameter(name = "age", description = "年龄", in = ParameterIn.QUERY)
})
@GetMapping("/{name}")
public List<User> getUsers(@PathVariable("name") String name, @RequestParam("age") Integer age) { 
}

注意：@Parameters里的@Paramete 使用 name 来找到方法中的入参，这块要对应上。

通过在接口方法上添加 @ApiResponses注解来表示一组响应信息（通常为一组错误信息）

@ApiOperation("获取用户信息")

@ApiResponses({ @ApiResponse(code=400,message="请求参数没填好"),
                @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
              })
@GetMapping("/getUser")
public User getUser(@PathVariable String name, @PathVariable String pwd) {
        System.out.println(name);
        System.out.println(pwd);
        return userRepository.getUserByNameAndPwd(name,pwd);
}

就不一一测试说明了...

注解属性	类型	描述
summary	String	接口的简要说明
description	String	接口的详细描述
tags	String[]	标签列表，可用于按资源或任何其他限定符对接口进行逻辑分组
responses	Class<?>	接口的返回类型
method	String	接口的请求方式

通过在 实体类及其属性 上添加 @Schema注解来对我们的 API 所涉及到的对象做描述。

同时，Springdoc 还支持 Java Bean Validation API 的注解，例如 @NotNull 等：

@Schema("用户实体")
public class User {
    @Schema("用户 id", example = "10001")  
    private int id;
    
    @NotNull
    @Schema(description = "名称", example = "王二狗")
    private String name;
    
    @NotNull
    @Min(18)
    @Max(35)
    @Schema(description = "年龄", example = "35")
    private Integer age;
    
    @Schema(description = "掌握的编程语言", type = "List", example = "[\"Java\",\"Sql\"]")
    private List<String> programmingLang;
}

效果如下：

注意红框中的内容，name 和 age 右上角都有出现了一个红色的星星，表示是必填的，age也被限制了范围。

二、集成Knife4j

1、Knife4j简介

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案，可以帮助开发者快速聚合使用OpenAPI规范。它为开发者在SwaggerUI的基础上提供了更为清晰的UI。

官方网址：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)

2、Spring Boot3集成Knife4j

（1）引入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

（2）配置文件

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

3、Spring Boot2集成Knife4j

（1）引入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

（2）配置文件

knife4j:
  enable: true
  openapi:
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    # aaa"
    email: xiaoymin@foxmail.com
    concat: 八一菜刀
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.knife4j.demo.new3