@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/skills/api-doc-generator/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: api-doc-generator
+description: |
+  API 文档生成技能。当用户提到以下关键词时触发：
+  API doc, Swagger, OpenAPI, 接口文档, SpringDoc,
+  接口说明, API 文档生成, 文档注解
+
+  本技能提供 Controller 到 OpenAPI/Swagger 注解的生成指导，
+  包括 SpringDoc 集成配置、常用注解使用、分组文档、
+  代码示例和常见问题排查。
+---
+
+# API 文档生成技能
+
+## 适用场景
+
+- 为已有 Controller 生成 OpenAPI 注解
+- 集成 SpringDoc 到 Avatar Boot 项目
+- 配置 API 文档分组
+- 自定义文档展示内容
+
+## SpringDoc 集成
+
+### 依赖配置
+
+```xml
+<!-- pom.xml (api 模块) -->
+<dependency>
+    <groupId>org.springdoc</groupId>
+    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+    <version>2.5.0</version>
+</dependency>
+```
+
+### 基础配置
+
+```yaml
+# application.yml
+springdoc:
+  api-docs:
+    enabled: true
+    path: /v3/api-docs
+  swagger-ui:
+    enabled: true
+    path: /swagger-ui.html
+    tags-sorter: alpha
+    operations-sorter: alpha
+  default-produces-media-type: application/json
+  default-consumes-media-type: application/json
+```
+
+### 全局配置类
+
+```java
+@Configuration
+public class OpenApiConfig {
+
+    @Bean
+    public OpenAPI customOpenAPI() {
+        return new OpenAPI()
+            .info(new Info()
+                .title("Avatar Boot 服务 API 文档")
+                .version("1.0.0")
+                .description("基于 Avatar Boot 框架的服务接口文档")
+                .contact(new Contact()
+                    .name("开发团队")
+                    .email("dev@example.com")))
+            .externalDocs(new ExternalDocumentation()
+                .description("项目文档")
+                .url("https://wiki.example.com"));
+    }
+}
+```
+
+## Controller 注解生成
+
+### 完整 Controller 示例
+
+```java
+@Tag(name = "用户管理", description = "用户信息的增删改查接口")
+@RestController
+@RequestMapping("/api/users")
+@RequiredArgsConstructor
+public class UserController {
+
+    private final UserService userService;
+
+    @Operation(
+        summary = "根据ID查询用户",
+        description = "根据用户ID查询用户详细信息，返回脱敏后的数据"
+    )
+    @ApiResponses({
+        @ApiResponse(responseCode = "200", description = "查询成功",
+            content = @Content(schema = @Schema(implementation = Result.class))),
+        @ApiResponse(responseCode = "200", description = "用户不存在（业务错误码非0）")
+    })
+    @GetMapping("/{id}")
+    public Result<UserInfoVO> getById(
+            @Parameter(description = "用户ID", required = true, example = "1")
+            @PathVariable Long id) {
+        return Result.success(userService.getById(id));
+    }
+
+    @Operation(summary = "创建用户", description = "创建新用户，用户名不可重复")
+    @PostMapping
+    public Result<Long> create(
+            @RequestBody @Valid UserInfoCreateDTO dto) {
+        return Result.success(userService.create(dto));
+    }
+
+    @Operation(summary = "更新用户信息")
+    @PutMapping("/{id}")
+    public Result<Void> update(
+            @Parameter(description = "用户ID", required = true)
+            @PathVariable Long id,
+            @RequestBody @Valid UserInfoUpdateDTO dto) {
+        userService.update(id, dto);
+        return Result.success();
+    }
+
+    @Operation(summary = "删除用户", description = "逻辑删除用户，关联数据不受影响")
+    @DeleteMapping("/{id}")
+    public Result<Void> delete(
+            @Parameter(description = "用户ID", required = true)
+            @PathVariable Long id) {
+        userService.delete(id);
+        return Result.success();
+    }
+
+    @Operation(summary = "分页查询用户列表")
+    @PostMapping("/page")
+    public Result<IPage<UserInfoVO>> page(
+            @RequestBody @Valid UserInfoPageQueryDTO dto) {
+        return Result.success(userService.page(dto));
+    }
+
+    @Operation(summary = "批量删除用户")
+    @DeleteMapping("/batch")
+    public Result<Void> batchDelete(
+            @Parameter(description = "用户ID列表", required = true)
+            @RequestBody List<Long> ids) {
+        userService.batchDelete(ids);
+        return Result.success();
+    }
+}
+```
+
+## 核心注解详解
+
+### @Tag — 接口分组
+
+```java
+// 用在 Controller 类上，定义接口分组
+@Tag(name = "用户管理", description = "用户信息的增删改查接口")
+@RestController
+public class UserController { }
+```
+
+### @Operation — 接口描述
+
+```java
+@Operation(
+    summary = "简要描述（显示在接口列表中）",
+    description = "详细描述（展开后显示）",
+    deprecated = false,        // 是否废弃
+    hidden = false             // 是否隐藏
+)
+```
+
+### @Parameter — 参数描述
+
+```java
+// 路径参数
+@Parameter(description = "用户ID", required = true, example = "1")
+@PathVariable Long id
+
+// 查询参数
+@Parameter(description = "用户名（模糊匹配）", example = "zhang")
+@RequestParam(required = false) String username
+
+// Header 参数
+@Parameter(description = "认证令牌", in = ParameterIn.HEADER, required = true)
+@RequestHeader("Authorization") String token
+```
+
+### @Schema — 模型描述
+
+```java
+@Data
+@Schema(description = "用户创建请求")
+public class UserInfoCreateDTO {
+
+    @Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED,
+            example = "zhangsan", maxLength = 50)
+    @NotBlank(message = "用户名不能为空")
+    private String username;
+
+    @Schema(description = "手机号", requiredMode = Schema.RequiredMode.REQUIRED,
+            example = "13812345678", pattern = "^1[3-9]\\d{9}$")
+    @NotBlank(message = "手机号不能为空")
+    private String phone;
+
+    @Schema(description = "邮箱", example = "zhangsan@example.com")
+    private String email;
+
+    @Schema(description = "用户状态", allowableValues = {"0", "1"},
+            defaultValue = "1", example = "1")
+    private Integer status;
+}
+```
+
+### @ApiResponse — 响应描述
+
+```java
+@ApiResponses({
+    @ApiResponse(responseCode = "200", description = "操作成功",
+        content = @Content(
+            mediaType = "application/json",
+            schema = @Schema(implementation = Result.class),
+            examples = @ExampleObject(value = """
+                {
+                  "code": 0,
+                  "message": "success",
+                  "data": { "id": 1, "username": "zhangsan" }
+                }
+                """)
+        )),
+    @ApiResponse(responseCode = "400", description = "参数校验失败"),
+    @ApiResponse(responseCode = "401", description = "未认证"),
+    @ApiResponse(responseCode = "403", description = "无权限")
+})
+```
+
+## 分组文档配置
+
+按模块或业务域对 API 进行分组：
+
+```java
+@Configuration
+public class OpenApiGroupConfig {
+
+    @Bean
+    public GroupedOpenApi userApi() {
+        return GroupedOpenApi.builder()
+            .group("1-用户管理")
+            .pathsToMatch("/api/users/**")
+            .build();
+    }
+
+    @Bean
+    public GroupedOpenApi orderApi() {
+        return GroupedOpenApi.builder()
+            .group("2-订单管理")
+            .pathsToMatch("/api/orders/**")
+            .build();
+    }
+
+    @Bean
+    public GroupedOpenApi systemApi() {
+        return GroupedOpenApi.builder()
+            .group("3-系统管理")
+            .pathsToMatch("/api/system/**")
+            .packagesToScan("com.example.controller.system")
+            .build();
+    }
+}
+```
+
+## Result<T> 泛型文档支持
+
+为了让 SpringDoc 正确解析 `Result<T>` 泛型，确保 Controller 方法的返回类型明确泛型参数：
+
+```java
+// 正确：明确泛型类型
+public Result<UserInfoVO> getById(...)
+
+// 正确：分页泛型
+public Result<IPage<UserInfoVO>> page(...)
+
+// 错误：原始类型，文档无法推断 data 结构
+public Result getById(...)
+```
+
+### Result 类注解
+
+```java
+@Data
+@Schema(description = "统一响应结构")
+public class Result<T> {
+
+    @Schema(description = "业务状态码，0表示成功", example = "0")
+    private Integer code;
+
+    @Schema(description = "响应消息", example = "success")
+    private String message;
+
+    @Schema(description = "响应数据")
+    private T data;
+}
+```
+
+## 生产环境关闭文档
+
+```yaml
+# application-prod.yml
+springdoc:
+  api-docs:
+    enabled: false
+  swagger-ui:
+    enabled: false
+```
+
+或使用条件配置：
+
+```java
+@Configuration
+@Profile("!prod")
+public class OpenApiConfig {
+    // 仅在非生产环境加载
+}
+```
+
+## 文档访问地址
+
+```
+Swagger UI:    http://localhost:8080/swagger-ui.html
+OpenAPI JSON:  http://localhost:8080/v3/api-docs
+OpenAPI YAML:  http://localhost:8080/v3/api-docs.yaml
+分组文档:       http://localhost:8080/v3/api-docs/1-用户管理
+```
+
+## 最佳实践
+
+1. **中文描述** — `summary` 和 `description` 使用中文，方便团队协作
+2. **示例值** — 每个字段提供 `example`，便于前端理解和调试
+3. **枚举说明** — 使用 `allowableValues` 说明枚举值含义
+4. **分组管理** — 按业务模块分组，方便查找
+5. **保持同步** — 注解与代码逻辑保持一致，避免文档与实际行为不符
+6. **生产关闭** — 生产环境必须关闭 Swagger UI
+7. **版本控制** — API 文档版本与应用版本一致
+8. **废弃标记** — 废弃接口使用 `@Deprecated` + `deprecated = true`
+
+## 常见问题排查
+
+### Swagger UI 页面空白
+
+```
+原因: 静态资源路径被拦截
+解决:
+  1. 检查 Security 配置是否放行 /swagger-ui/** 和 /v3/api-docs/**
+  2. 检查是否有自定义 WebMvcConfigurer 覆盖了资源映射
+```
+
+### 泛型类型显示为 Object
+
+```
+原因: 返回类型使用了原始 Result 而非 Result<T>
+解决:
+  1. Controller 方法返回值明确泛型参数
+  2. 使用 @Schema 注解标注 DTO 字段类型
+```
+
+### 分页响应结构不正确
+
+```
+原因: IPage 接口的泛型推断问题
+解决:
+  1. 使用具体实现类 Page<T> 替代 IPage<T> 作为返回类型
+  2. 或自定义 PageVO<T> 作为响应类型
+```
+
+### 文档加载缓慢
+
+```
+原因: 扫描了过多的包路径
+解决:
+  1. 使用 packagesToScan 限制扫描范围
+  2. 使用 pathsToMatch 限制匹配路径
+  3. 排除不需要文档的内部接口
+```