SpringBoot集成Swagger3

Swagger 是一个 API 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为 17 年发布的 Swagger3。

Swagger 是一个规范和完整的框架，用于生成可视化 RESTful 风格的 Web 服务。

1. 导入依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.4</version>
</dependency>

2. 添加配置类

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI myWebCloudDisk() {
        return new OpenAPI()
                .info(new Info()
                        .title("接口文档名称")
                        .description("接口文档描述")
                        .version("v1.0")
                        .license(new License().name("MIT").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("gitee地址")
                        .url("https://www.baidu.com"));
    }

}

3. 使用注解
   • @Tag注解：用来描述一组操作的信息（通常用在controller控制层类上）

属性	描述
name	标签名
description	描述
externalDocs	添加一个扩展文档
extensions	可选的扩展列表

例子：

@Tag(name = "user", description = "该接口为用户接口，主要做用户登录、注册和校验token")

2. @Operation注解：用来描述接口信息（通常用在控制层的具体方法上）

属性	描述
method	HTTP请求方法
tags	按照资源对操作进行逻辑分组
summary	简要说明
description	详细描述
requestBody	与操作关联的请求报文
parameters	一个可选的参数数组
responses	执行此操作返回的可能响应的列表
deprecated	允许将操作标记为已弃用
security	可用于此操作的安全机制的声明

例子：

@Operation(summary = "用户注册", description = "注册账号", tags = {"users"})

3. @Schema注解：该注解用来定义模型及模型的属性（通常可以用在dto/vo上以及其属性上）

常用属性	描述
description	描述

例子

@Schema(description = "登录Dto")
public class LoginDto {
    @Schema(description = "手机号")
    private String telephone;
    @Schema(description = "密码")
    private String password;
}

4.启动项目，在url路径后面添加**/swagger-ui.html**即可访问到文档页面