参看

https://swagger.io/
https://springdoc.org/

https://www.bilibili.com/video/BV1F44y1t7aK

http://itboyhub.com/2021/01/29/springboot-swagger3

Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证API 文档的及时性将有很大的帮助。

swagger3支持OpenAPI，发布于2020年7月。它的很多使用细节与swagger2中一致，这里就不做出多的解释【点击我，快速学习swagger2】。

swagger3对于swagger2的优势：

支持OpenAPI。
无需配置，即可开启。

一、快速使用

对于swagger2来说，需要引入依赖有：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

一个用来生成接口文档（JSON 数据），另一个用来展示将 JSON 可视化。

而在swagger3中，使用一个starter就解决了

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

和 Spring Boot 中的其他 starter 一样，springfox-boot-starter 依赖可以实现零配置以及自动配置支持。即如果没有其他特殊需求，加一个这个依赖，接口文档就自动生成了。

启动项目之后，访问http://localhost:8080/swagger-ui/index.html进入测试接口页面（访问接口自设）。

二、增加配置类

这是使用swagger的核心，对于 开关、分组和过滤 等信息的配置，都是在config类中进行配置。

1.application

server:
  port: 8082

config:
  swagger3:
    flag: true

2.Swagger3Config

在Swagger中添加JWT认证，点击我跳转

package com.pdh.file.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;

/** * @Author: 彭_德华 * @Date: 2021-10-14 14:57 * 覆盖默认的配置信息 */
@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Value("${config.swagger3.flag}") //读取配置文件
    private boolean flag;

    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.OAS_30) // 指定3.0版本
                .groupName("文件上传")
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pdh.file.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){

        return new ApiInfo("基于SpringBoot上传文件",
                "基于SpringBoot，实现上传文件到本地电脑和上传文件到云服务器（以七牛云服务器为例）",
                "v1.0",
                "https://blog.csdn.net/yeahPeng11",
                new Contact("彭德华","https://blog.csdn.net/yeahPeng11","pdhcool@163.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

配置类的写法和作用，可参考并查看swagger2。

三、接口的地址

3.0 中的接口地址也和之前有所不同，以前在 2.9.2 中我们主要访问两个地址：

文档接口地址：http://localhost:8080/v2/api-docs
文档页面地址：http://localhost:8080/swagger-ui.html

现在在 3.0 中，这两个地址也发生了变化：

文档接口地址：http://localhost:8080/v3/api-docs
文档页面地址：http://localhost:8080/swagger-ui/index.html

特别是文档页面地址，如果用了 3.0，而去访问之前的页面，会报 404。

访问截图：

四、注解

支持swagger2的所有注解，并且在 3.0 中还提供了一些其他注解。例如使用：

@EnableOpenApi 代替以前旧版本中的 @EnableSwagger2。
@ApiOperation 代替以前旧版本中的 @Operation。

常用注解

这几个注解使用起来都是非常的简单，可结合源码使用（源码一看就懂）

@Api：用在controller类，描述API接口
@ApiOperation：描述接口方法
@ApiModel：描述对象
@ApiModelProperty：描述对象属性
@ApiImplicitParams：描述接口参数
@ApiResponses：描述接口响应
@ApiIgnore：忽略接口方法

Swagger3快速使用