Swagger

Swagger 是一种 RESTful API 的规范，提供了完整的 API 文档解决方案。Spring 官方推荐使用 SpringDoc 替代原生 Swagger。

适用场景

RESTful API 接口文档自动生成、前后端协作、API 测试调试。

引入依赖

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

基本配置

springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs

常用注解

注解	说明
@Tag	接口分组描述
@Operation	描述单个接口
@Schema	描述字段信息
@ApiResponse	描述响应状态码
@Parameter	描述请求参数

使用示例

@RestController
@RequestMapping("/users")
@Tag(name = "用户管理", description = "用户增删改查接口")
public class UserController {

    @Operation(summary = "获取用户", description = "根据ID获取用户信息")
    @ApiResponse(responseCode = "200", description = "成功")
    @GetMapping("/{id}")
    public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
        return userService.getUser(id);
    }
}

Knife4j

Knife4j 是对 Swagger UI 的增强，提供更好的文档界面和调试功能：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

访问地址：http://localhost:8080/doc.html

常见问题

问题	解决方案
Swagger UI 无法访问	确认依赖已引入；检查路径 /swagger-ui.html 或 /doc.html；确认 Spring Security 未拦截
接口文档不显示	确认方法上有 @Operation 注解；检查 @RestController 是否正确；确认组件扫描路径