SpringDoc 接口文档管理

编写接口文档是日常开发中必不可少的一环。比较古早的时代，我们的接口文档可能就是一个DOCX文件，后来又逐渐演变出了类似Yapi等API管理平台。而在Java开发中，SpringDoc是比较常用的一种接口管理工具，它能够基于Java代码注解生成符合OpenAPI 3.0规范的API文档，SpringDoc还内置了swagger-ui页面来展示API文档。此外，由于API文档是遵循OpenAPI规范实现的，因此也能够很方便的导入其他管理平台。

Swagger、OpenAPI和SpringDoc之间的关系

Swagger最初是一个用于生成、描述和可视化Web API的工具集，它内置了一整套用于描述Web API的JSON描述规范，并提供了Swagger UI和Swagger Editor工具，用于展示和编辑API文档。2015年，Swagger被捐赠给OpenAPI Initiative，其对Web API的JSON描述规范部分被重新命名为OpenAPI规范，其最新版本是3.0。

SpringDoc是Java中一个实现了OpenAPI3.0规范的工具包，它能够集成到Spring等框架中，自动根据Java代码注解生成基于OpenAPI3.0规范的在线接口文档。SpringDoc也集成了Swagger UI组件，用于以Web方式展示接口文档。使用SpringDoc生成接口文档非常方便，它省去了我们手动向API管理平台录入接口的麻烦，当然，SpringDoc的最大缺点就是侵入式的代码设计，使用SpringDoc会导致我们的控制器类中充斥着业务逻辑无关的注解，这一点广受诟病，我们根据具体需求自行选择。

关于SpringFox和SpringDoc：在早期能够集成SpringBoot生成Swagger（SpringFox使用OpenAPI2.0规范）文档的库是SpringFox，但后来这个库停止更新了，且不支持最新版的SpringBoot2.7，因此对于新版本SpringBoot我们应使用SpringDoc而不是SpringFox。

引入SpringDoc依赖

SpringBoot2.7对应的SpringDoc版本是1.8.0，我们可以直接引入相关起步依赖。

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

相关工程配置

在SpringBoot工程中的application.properties中，我们可以配置OpenAPI文档和SwaggerUI的开启和关闭，以及它们注册的HTTP路径。

springdoc.api-docs.enabled=true
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html

注意：一般来说，生产环境我们应该关闭OpenAPI文档和SwaggerUI！

SpringDoc使用例子

API文档通常包含如下几个重要信息：

• 接口路径、方法等，和接口说明
• 请求参数和说明
• 响应参数和说明

实际上，SpringDoc的作用就是提供了一系列注解来标注上述信息，工程启动后会扫描相关注解并输出为符合OpenAPI 3.0规范的接口文档，并加载到内置的SwaggerUI页面上展示。这部分都比较容易理解，我们直接看一个例子。

Student.java

package com.gacfox.demo.model;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "包含学生基本信息字段")
public class Student {
    @Schema(description = "学号")
    private String studentId;
    @Schema(description = "姓名")
    private String studentName;
    @Schema(description = "年龄")
    private Integer age;
    @Schema(description = "性别")
    private String gender;
    @Schema(description = "高考分数")
    private Integer score;
}

这部分代码是一个实体类，我们在类和字段上标注@Schema，该注解的name属性默认取类名和字段名，我们通常不需要修改；description是其描述信息。

StudentController.java

package com.gacfox.demo.controller;

import com.gacfox.demo.model.Student;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "学生信息接口")
@RestController
@RequestMapping(value = "/api/student")
public class StudentController {
    @Operation(summary = "根据学号查询学生")
    @Parameters({
            @Parameter(name = "studentId", description = "学号", required = true)
    })
    @GetMapping(value = "/getStudentById")
    public Student getStudentById(String studentId) {
        Student student = new Student();
        student.setStudentId("1234567");
        student.setStudentName("小明");
        student.setAge(21);
        student.setGender("male");
        student.setScore(650);
        return student;
    }
}

上面代码是一个SpringMVC控制器，我们在类上标注了@Tag作为该控制器的文档说明，控制器方法上标注了@Operation，为对应的HTTP接口标注文档，@Parameters标注请求参数。

访问swagger-ui页面

我们启动工程后，可以直接访问/swagger-ui/index.html，查看所有的接口信息。

忽略内容

SpringDoc默认会扫描所有包路径下的Controller接口，如果我们想忽略一些内容，可以使用@Hidden注解。

Swagger注解

这里我们整理一下SpringDoc支持的注解。