Knife4j 接口文档

一、为什么需要接口文档

前后端分工后，接口是团队的"契约"：

• 前端：照着文档调接口，不依赖后端代码。
• 后端：照着文档实现，不依赖前端期待。
• 新同事入职：看文档快速上手。

手写文档（Word/Markdown）容易过期，Knife4j 从代码注解自动生成文档，改动即同步，还能在线调试。

二、引入 Knife4j

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

Spring Boot 3 用 jakarta 版；Spring Boot 2 用 knife4j-spring-boot-starter。

无需配置，启动后访问：

http://localhost:8080/doc.html

页面里能看到所有接口、参数、返回值，并且支持"调试"按钮在线调用。

三、用注解写文档

@Tag(name = "购物车", description = "购物车接口")
@RestController
@RequestMapping("/api/cart")
public class CartController {

    @Operation(summary = "查询我的购物车", description = "需登录")
    @GetMapping
    public Result<List<CartItemVO>> list() {
        return Result.ok(cartService.list(AuthInterceptor.USER_ID.get()));
    }

    @Operation(summary = "加入购物车")
    @PostMapping
    public Result<Void> add(@RequestBody @Valid CartAddDTO dto) {
        cartService.add(AuthInterceptor.USER_ID.get(), dto);
        return Result.ok(null);
    }
}

DTO 字段说明：

@Data
public class CartAddDTO {
    @Schema(description = "商品 ID", example = "1")
    @NotNull(message = "商品不能为空")
    private Long productId;

    @Schema(description = "数量", example = "2", defaultValue = "1")
    @Min(value = 1, message = "数量至少为 1")
    private Integer count;
}

常用注解：

注解	位置	作用
@Tag	类	分组名称
@Operation	方法	接口摘要/描述
@Schema	DTO 字段	字段说明/示例
@Parameter	参数	单个参数的说明

四、全局参数（token）

需要登录的接口，在 Knife4j 里统一配置 Authorization 参数，联调时填一次 token：

// config/Knife4jConfig.java
@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
            .info(new Info().title("商城 API").description("全栈教程商城系统")
                .version("v1.0"))
            .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
            .components(new Components().addSecuritySchemes("BearerAuth",
                new SecurityScheme().type(SecurityScheme.Type.HTTP)
                    .scheme("bearer").bearerFormat("JWT")));
    }
}

五、文档驱动的开发流程（企业日常）

1. 需求评审 → 定接口清单（粗粒度）
2. 后端先写 Controller 骨架 + 注解 → 生成文档
3. 前端照着文档开发（此时后端可只返回 Mock 数据）
4. 并行开发 → 联调 → 文档实时更新（改代码即改文档）

这就是"接口先行"协作模式：契约先定好，前后端并行开发，效率最高。

六、本章验收

• [ ] http://localhost:8080/doc.html 打开，能看全所有接口
• [ ] 在文档页点击"调试"，带 token 调用加购接口成功
• [ ] 注解写全：类、方法、DTO 字段都有说明