今天接到的任务，是在公司的 Spring Boot 3 项目中接入 Swagger，自动生成 API 文档。刚开始我觉得需求比较简单，直接把项目版本和要求发给 AI，让它生成代码即可。

AI 很快给出了配置，但运行时却出现了问题。检查后发现，它生成的是旧版 Springfox 方案，使用了 @EnableSwagger2、Docket 和 @ApiOperation，并不适合当前的 Spring Boot 3 项目。

我重新强调项目版本，让 AI 改用 Springdoc OpenAPI。首先在 pom.xml 中加入依赖：

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

随后使用 OpenAPI 3 注解描述接口：

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理")
public class UserController {

    @GetMapping
    @Operation(summary = "查询用户列表")
    public List<String> listUsers() {
        return List.of("Tom", "Jerry");
    }
}

项目启动后，访问以下地址即可查看接口文档并在线测试：

http://localhost:8080/swagger-ui.html

OpenAPI 的 JSON 数据可以通过下面的地址查看：

http://localhost:8080/v3/api-docs

metor看完我的开发过程后问：“这些固定步骤，下次还要重新解释一遍吗？”他建议我把这套流程整理成一个 Skill。

于是，我将流程拆成几个固定步骤：先识别 Spring Boot 版本，再选择兼容的 Swagger 方案；随后添加依赖、补充接口注解；最后启动项目，检查 Swagger UI 和 OpenAPI JSON 是否能够正常访问。

第一版 Skill 仍有不足，例如没有检查项目中是否残留旧版 Springfox 依赖，也没有要求 AI 验证访问路径。我根据测试结果补充规则，让 AI 在生成代码前先判断版本，生成后再检查依赖、注解和访问地址。

今天最大的收获，不只是学会了在 Spring Boot 3 中接入 Swagger，而是开始理解 Skill 的作用。它不是让 AI 突然获得新能力，而是把已经验证过的开发步骤沉淀下来。下次遇到相似任务时，不需要重新解释一遍，AI 也能按照更稳定的流程完成开发。