一个叫Swagger的工具，让写接口文档变成享受

---知识点专栏---

Swagger/SpringDoc 从入门到上手使用

前言

在前后端分离的项目开发中，一份清晰、实时更新的接口文档至关重要。它不仅能减少沟通成本，还能提高开发与联调效率。

Swagger 正是为此而生。它能根据代码自动生成接口文档，并内置测试功能。

本文以一个"在线OJ系统"为例，带你从零掌握 Swagger（SpringDoc）的核心用法。

一、为什么需要统一的接口文档？

在没有规范文档时，我们常遇到这些痛点：

• 格式不一致：不同接口返回的数据结构各异，前端要写多套解析逻辑。
• 错误难定位：缺乏统一的状态码，报错信息千奇百怪。
• 维护噩梦：人员变动后，新成员需要翻代码才能知道接口定义。

因此，我们先定义了统一的响应格式和状态码体系。

1. 统一响应体：R<T>

所有接口都套用此结构，包含状态码、消息和数据。

public class R<T> {
    private int code;    // 状态码
    private String msg;  // 提示消息
    private T data;      // 数据体
}

2. 自定义业务状态码

我们使用枚举 ResultCode 来管理状态，比单纯用HTTP状态码更安全、语义更明确。

@Getter
@AllArgsConstructor
public enum ResultCode {
    SUCCESS(1000, "操作成功"),
    ERROR(2000, "服务繁忙请稍后重试"),
    FAILED(3000, "操作失败"),
    FAILED_UNAUTHORIZED(3001, "未授权"),
    FAILED_PARAMS_VALIDATE(3002, "参数校验失败"),
    FAILED_NOT_EXISTS(3003, "资源不存在"),
    FAILED_ALREADY_EXISTS(3004, "资源已存在"),
    FAILED_USER_EXISTS(3101, "用户已存在"),
    FAILED_USER_NOT_EXISTS(3102, "用户不存在"),
    FAILED_LOGIN(3103, "用户名或密码错误"),
    FAILED_USER_BANNED(3104, "您已被列入黑名单，请联系管理员."),
    
    // ... 其他状态码
}

有了这些基础后，Swagger就能把这些状态码和响应结构清晰地展示给前端。

二、什么是 Swagger / SpringDoc？

Swagger 是一套开源的API文档工具。在Spring Boot项目中，我们通常使用 SpringDoc 这个库，它实现了Swagger的规范，能自动扫描接口并生成可交互的在线文档。

三、项目实战：引入 SpringDoc

1. 创建公共模块并引入依赖

我们在项目中创建一个公共模块 oj-common-swagger，在它的 pom.xml 中加入：

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

2. 编写 Swagger 配置类

新建 SwaggerConfig.java，用来设置文档的标题、描述和版本：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                .title("在线OJ系统")
                .description("在线OJ系统接口文档")
                .version("v1"));
    }
}

3. 让Spring Boot自动装配

为了让其他服务引入该模块时配置能自动生效，在 resources 目录下创建文件：
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

文件内容为你的配置类全路径：

com.site.common.swagger.config.SwaggerConfig

4. 在业务服务中使用

比如在 oj-sys-server 服务中，引入公共模块即可：

<dependency>
    <groupId>com.bite</groupId>
    <artifactId>oj-common-swagger</artifactId>
    <version>${oj.common.swagger.version}</version>
</dependency>

启动项目后，访问 http://localhost:你的端口/swagger-ui/index.html 就能看到文档页面了。

四、使用注解细化接口文档

光有"骨架"还不够，我们需要用注解来详细描述每个接口。

1. @Tag：给Controller打标签

用在类上，对接口进行分组。

@RestController
@RequestMapping("/sysUser")
@Tag(name = "管理员用户API")
public class SysUserController {
    // ...
}

2. @Operation 和 @ApiResponse：描述接口与响应

用在方法上，说明接口的作用及可能返回的状态码。

@Operation(summary = "新增管理员", description = "根据提供的信息新增管理员用户")
@PostMapping("/add")
@ApiResponse(responseCode = "1000", description = "操作成功")
@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")
@ApiResponse(responseCode = "3101", description = "用户已存在")
public R<VoId> add(@RequestBody SysUserSaveDTO saveDTO) {
    return null;
}

3. @Parameter：描述输入参数

用于明确参数的名称、位置（路径、查询等）和描述。

路径参数示例：

@DeleteMapping("/{userId}")
@Operation(summary = "删除用户", description = "通过用户id删除用户")
@Parameters(value = {
    @Parameter(name = "userId", in = ParameterIn.PATH, description = "用户ID")
})
@ApiResponse(responseCode = "1000", description = "成功删除用户")
@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")
@ApiResponse(responseCode = "3101", description = "用户不存在")
public R<VoId> delete(@PathVariable Long userId) {
    return null;
}

查询参数示例：

@Operation(summary = "用户详情", description = "根据查询条件查询用户详情")
@GetMapping("/detail")
@Parameters(value = {
    @Parameter(name = "userId", in = ParameterIn.QUERY, description = "用户ID"),
    @Parameter(name = "sex", in = ParameterIn.QUERY, description = "用户性别")
})
@ApiResponse(responseCode = "1000", description = "成功获取用户信息")
@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")
@ApiResponse(responseCode = "3101", description = "用户不存在")
public R<SysUserVO> detail(Long userId, @RequestParam(required = false) String sex) {
    return null;
}

五、在线测试：Swagger 的"隐藏大招"

Swagger UI 不只用来"看"，更强大的是直接在网页上测试接口。

1. 打开页面后，找到你要测试的接口（比如"新增管理员"）。

2. 点击 Try it out 按钮。

3. 按照文档提示，在 Request body 中填入正确的JSON参数。

4. 点击 Execute 发送请求。
   

页面上会立刻展示出真实的响应体、响应状态码等信息，完全不需要打开Postman。这在开发阶段能极大地提升效率。

总结

用好 Swagger / SpringDoc，核心在于做好两点：

1. 先定义好统一的响应格式和状态码，让文档有规可循。
2. 熟练使用 @Tag、@Operation、@ApiResponse、@Parameter 等注解，把接口信息详尽、准确地描述出来。

Swagger 官方：https://swagger.io/
SpringDoc 官方：https://springdoc.org/#swagger-ui-support