Spring Boot 整合 Swagger 实现接口文档

本文介绍 OpenApi、Swagger、SpringFox 和 SpringDoc 之间的区别，以及 SpringBoot 如何整合并使用 Swagger 实现接口文档。

名词解释

• OpenApi 是什么？

解答： OpenApi 是一个用于描述、定义和共享 RESTful API 文档的规范。最新规范是 OpenAPI 3.0。

• Swagger 是什么？

解答： Swagger 是一个用于设计和测试 RESTful API 的工具，是无关语言的。它提供了 API 描述、请求和响应示例、API 测试和文档生成等丰富的功能。最新版本是 Swagger 3，支持 OpenAPI 3.0 规范。

• SpringFox 是什么？

解答： SpringFox 是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 2 集成到 Spring 中。

地址：https://github.com/springfox/springfox

• SpringDoc 是什么？

解答： SpringDoc 也是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 3 集成到 Spring 中。SpringDoc 支持 Swagger 页面、Oauth2 登录，相较于 SpringFox 而言，它的支撑时间更长，无疑是更好的选择。

地址：https://springdoc.org/

• 它们之间的关系

解答： OpenAPI 定义了一种标准的格式来表示 API 文档，而 Swagger 是一个实现 OpenAPI 规范的工具，而 SpringFox 和 SpringDoc 都是将 Swagger 继承到 Spring 框架中方便使用。

开始

如何将 Swagger 集成到 SpringBoot 中？

环境

• JDK 17
• SpringBoot 3

在 SpringBoot 3 之前用的都是 SpringFox 来集成 Swagger 管理我们的 API 接口文档，但是 SpringFox 已经停止更新了，本次我们使用的是 SpringBoot 3 、JDK 17 的环境，推荐使用 SpringDoc 来整合 Swagger。

添加依赖

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

编写 Controller 类

@RestController
public class HelloController {
 
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

访问接口页面

浏览器直接输入：http://localhost:8080/swagger-ui/index.html 回车即可看到下面界面：

配置

在 application.yml 中可以自定义 api-docs 和 swagger-ui 的访问路径，扫描的指定包等等。

springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: false # 关闭接口文档，可针对 application-dev.yml / application-test 进行不同配置
  swagger-ui:
    path: /swagger-ui.html
  packages-to-scan: com.example.swaggerdemo.common.controller # 只显示 common 包下的接口

可以通过配置类来自定义 swagger-ui 页面信息：

@OpenAPIDefinition(
        // 不同环境的服务器地址
        servers = {
                @Server(description = "开发环境服务器", url = "http://localhost:8080"),
                @Server(description = "测试环境服务器", url = "https://test.xiezhr.com")
        },
        // 配置外部文档地址
        externalDocs = @ExternalDocumentation(
                description = "项目编译部署说明",
                url = "http://localhost:8080/deplay/readme.md"
        )
)
 
@Configuration
public class SpringDocConfig {
 
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置接口文档基本信息
                .info(this.getApiInfo())
                ;
    }
 
    private Info getApiInfo() {
        return new Info()
                 // 配置文档标题
                .title("SpringBoot3集成Swagger3")
                // 配置文档描述
                .description("SpringBoot3集成Swagger3示例文档")
                // 配置作者信息
                .contact(new Contact().name("程序员小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
                // 配置License许可证信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                //
                .summary("SpringBoot3集成Swagger3示例文档aaa")
                .termsOfService("https://www.xiezhrspace.cn")
 
                // 配置版本号
                .version("2.0");
    }

    // 对接口进行分组
    @Bean("commonGroupApi")
    public GroupedOpenApi webGroupApi() {
        return GroupedOpenApi.builder().group("common通用模块组")
            .pathsToMatch("/common/**")
            .build();
    }
 
    @Bean("adminGroupApi")
    public GroupedOpenApi adminGroupApi() {
        return GroupedOpenApi.builder().group("admin模块组")
            .pathsToMatch("/admin/**")
            .build();
    }
}

注解使用

Controller 类

① @Tag 注解，用于类上。

• name: 名称
• description: 接口描述信息

② @Operation 注解，用在方法上。

• summary：方法概要，方法的一个简单介绍，建议 120 个字符内
• description：方法描述，一般是很长的内容
• hidden：是否隐藏

③@Parameter 注解，用在方法参数上。

• name：指定的参数名
• in：参数位置，可选 query、header、path 或 cookie，默认为空，表示忽略
• description：参数描述
• required：是否必填，默认为 false

④ @ApiResponse 注解，用于说明一个响应信息，用在 @ApiResponses 中。

• responseCode：HTTP 响应码
• description：描述

@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
 
    @Autowired
    private IUserService userService;
 
   @GetMapping("/hello")
   @Operation(summary = "hello接口", description = "hello接口描述", hidden = true)
    public String hello(){
        return "hello";
    }
 
    @GetMapping("/hi")
    @Operation(summary = "hi接口", description = "hi接口描述")
    public String Hi(){
        return "Hi 程序员小凡";
    }
 
    @GetMapping("/user/{id}")
    @Operation(summary = "获取用户信息", description = "根据用户ID获取用户信息")
    @ApiResponses(value ={
            @ApiResponse(responseCode = "200", description = "请求成功"),
            @ApiResponse(responseCode = "404", description = "用户不存在")
    })
    public User getUser( @Parameter(name = "id", in = ParameterIn.PATH, description = "用户ID", required = true) @PathVariable("id") Integer id){
        User user = userService.getUserById(id);
        return user;
    }
}

⑤@RequestHeader 注解。

很多时候我们接口都需要认证之后才能访问，这时候我们就需要接口调用的时候携带着 token 信息，我们通过 @RequestHeader 注解，获取请求头中 token 信息。

@GetMapping("/index")
public String  admin(@RequestHeader ("token") String token){
	System.out.println("token>>>>>>>>>>>>>>>>>>>>>>>>" + token);
    //token 验证
    //.....各种业务逻辑
    return "admin";
}

实体类

@Schema 注解，用于描述数据对象信息或数据对象属性，用在类或类属性上。

• name: 属性名称
• description: 属性描述
• required: 是否必须
• minLength: 字符最小长度
• maxLength: 字符最大长度

@Data
@Schema(description = "用户实体类", name = "User")
public class User {
    @Schema(description = "用户名", name = "name", minLength = 6, maxLength = 20, required = true)
    private String name;
    @Schema(description = "年龄", name = "age", required = true, minimum = "1", maximum = "100")
    private Integer age;
    @Schema(description = "邮箱", name = "email", required = true)
    private String email;
    @Schema(description = "地址", name = "address")
    private String address;
}