Swagger3快速使用

• 一、快速使用
• 二、增加配置类
• • 1.application
  • 2.Swagger3Config
• 三、接口的地址
• 四、注解
• • 常用注解

参看

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来说，需要引入依赖有：

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

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

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

    io.springfox
    springfox-boot-starter
    3.0.0

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

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

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

server:
  port: 8082

config:
  swagger3:
    flag: true

在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;


@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：忽略接口方法