--- author: Peanut created_at: 2026-05-23 purpose: 设计接口管理页面的中文描述补全和测试面板表单化改造 --- # 接口管理中文描述与测试面板改造设计 ## 1. 目标 - 所有接口均有对应的中文描述（summary + description），在接口列表和详情中可直观理解接口用途 - 所有参数均有中文描述，在详情和测试面板中可理解参数含义 - 测试面板从"空白 JSON 输入框"改造为"预填充 JSON 编辑器"——参数 key 和结构预填充，用户只需修改值即可测试 - 操作列增加"测试"按钮，点击直接打开弹窗并切换到测试标签 ## 2. 架构 ``` 后端 Controller (@Operation/@Parameter/@Schema 注解) → SpringDoc 自动生成 OpenAPI 3 JSON (/v3/api-docs) → ApiEndpointService.syncFromOpenApi() 解析并入库 → 前端 getEndpointList/getEndpointDetail 展示 → 前端 EndpointDetailDialog 测试面板渲染预填充 JSON 表单 ``` ## 3. 后端改造 ### 3.1 Controller 注解补全 为 `backend-single/src/main/java/com/emotion/controller/` 下所有 Controller 补全注解： **类级别注解：** ```java @Tag(name = "用户管理", description = "用户的增删改查、状态管理等操作") public class UserController { ... } ``` **方法级别注解：** ```java @Operation(summary = "分页查询用户列表", description = "支持按用户名、状态、角色等条件筛选") @GetMapping("/list") public Result> list(@Validated UserQueryRequest request) { ... } ``` **参数级别注解（路径参数/查询参数）：** ```java @Parameter(description = "用户ID", required = true) @RequestParam String userId ``` **DTO 字段注解（请求体参数）：** ```java public class LoginRequest { @Schema(description = "手机号") private String phone; @Schema(description = "短信验证码") private String smsCode; } ``` ### 3.2 注解补全范围与批次 按优先级分批补全，每批完成后触发同步验证： **Batch 1 (P0 - 认证与管理，约 5 个 Controller，~25 个接口):** - AuthController, AdminAuthController, GuestUserController, TokenController, AdminController - 涉及核心请求体：登录/注册/重置密码等，参数描述最关键 **Batch 2 (P1 - AI 与社区，约 8 个 Controller，~40 个接口):** - AiChatController, AiConfigController, AiRoutingController, CozeApiCallController - CommunityPostController, CommentController, SocialContentController, SocialInsightController - UserProfileController, UserController **Batch 3 (P1 - 日记与情绪，约 8 个 Controller，~35 个接口):** - DiaryPostController, DiaryCommentController, GrowthTopicController, TopicInteractionController - EmotionAnalysisController, EmotionRecordController, EmotionSummaryController, LifeEventController - ConversationController, MessageController **Batch 4 (P2 - 其他，约 10+ 个 Controller，~30 个接口):** - DictionaryController, EpicScriptController, LifePathController, AchievementController - RewardController, UserStatsController, TtsController, AsrController, HealthController - AnalyticsController, AdminAnalyticsController, ChatWebSocketController **完成标准：** 每个批次的 Controller 及其关联的 Request/Response DTO 全部注解补全。 ### 3.3 同步逻辑 `ApiEndpointServiceImpl.syncFromOpenApi()` 已经正确解析 OpenAPI 规范中的 `summary`、`description`、`parameters[].description`、`requestBody` schema 中的字段描述。补全注解后在管理后台点击"手动同步"即可生效。 ## 4. 前端改造 ### 4.1 EndpointList.vue — 操作列增加"测试"按钮 在操作列添加"测试"按钮，点击后打开详情弹窗并自动切换到测试标签页： ```vue ``` `showTest(row)` 方法：加载详情后，通过 `defaultTab` prop 控制子组件默认打开测试标签。 ### 4.2 EndpointDetailDialog.vue — 测试面板改造 #### 4.2.1 新增 defaultTab prop 父组件可控制默认打开的标签页： ```typescript const props = defineProps<{ modelValue: boolean detail: ApiEndpointDetail | null defaultTab?: 'detail' | 'test' // 新增，默认 'detail' }>() ``` watch 逻辑中： ```typescript watch(() => props.detail, (ep) => { if (ep) { testForm.value.path = ep.path testForm.value.method = ep.method testForm.value.params = {} testForm.value.body = '' testResult.value = null activeTab.value = props.defaultTab || 'detail' // 使用传入的默认标签 } }, { immediate: true }) ``` #### 4.2.2 查询参数表单化（GET/DELETE 等无请求体的接口） 对于 `paramType` 为 `query` 或 `path` 的参数，渲染为表单输入框： | paramTypeDef | enumValues 有值 | 渲染组件 | |-------------|----------------|---------| | string | 有 | `` 下拉选择 | | string | 无 | `` 文本输入 | | integer/number | 有 | `` 下拉选择 | | integer/number | 无 | `` 数字输入 | | boolean | - | `` 开关 | | array | - | `` 文本输入（逗号分隔） | | object | - | 暂不支持，fallback 到文本输入 | 每个参数显示： - **label**: 参数中文描述（description），无描述则显示参数名（name） - **placeholder**: 示例值（example）或数据类型提示 - **必填标记**: required=1 时 label 旁显示红色星号 #### 4.2.3 请求体预填充（POST/PUT/PATCH） 对于有请求体的接口，使用 JSON 编辑器（``）但预填充完整结构： **预填充算法：** ``` function generateJsonTemplate(schema): if schema is null or empty object: return "" result = {} for each [key, prop] in schema.properties: if prop.example exists and is not empty: result[key] = parseExample(prop.example) // 尝试解析为对应类型 else if prop.type == "string": result[key] = "" else if prop.type == "integer": result[key] = 0 else if prop.type == "number": result[key] = 0.0 else if prop.type == "boolean": result[key] = false else if prop.type == "array": result[key] = [] else if prop.type == "object" and prop.properties: result[key] = generateJsonTemplate(prop) // 递归 else: result[key] = null // 对 required 字段但没有 example 的，保留空值占位 // 对非 required 且无 example 的可选字段，省略该 key for each key in result: if key not in schema.required and result[key] in [null, "", 0, false, []]: delete result[key] return JSON.stringify(result, null, 2) ``` **数据来源优先级：** 1. 先从 `detail.params` 中找 `paramType === 'body'` 的参数，用其 description/example 填充 2. 如果没有 body 类型参数，从 `detail.requestSchema` 解析 JSON Schema 生成 **UI 展示：** ``` 请求体 (JSON) ──────────────────────────────────────────┐ │ { │ │ "phone": "13800138000", │ │ "smsCode": "123456" │ │ } │ └──────────────────────────────────────────┘ 💡 参数结构已预填充，修改值后点击"发送请求"即可 ``` #### 4.2.4 请求头展示 在参数配置区域下方展示自动添加的请求头（只读）： ``` 请求头 ┌──────────────────────────────────────────┐ │ Authorization: Bearer eyJhbGci...xxx │ │ Content-Type: application/json │ └──────────────────────────────────────────┘ ``` - `Authorization`: 根据 tokenSource 自动设置 - `Content-Type`: POST/PUT/PATCH 且有请求体时自动添加 #### 4.2.5 路径处理 测试代理接口要求路径以 `/api` 开头（SSRF 防护）。前端发送测试请求时，自动在 endpoint path 前拼接 `/api`： ```typescript path: '/api' + testForm.value.path // 例如 /api + /auth/login = /api/auth/login ``` ### 4.3 边缘情况处理 | 场景 | 处理方式 | |------|---------| | `requestSchema` 为 `{}` 或 `null` | 请求体显示空 textarea，placeholder: "此接口无请求体参数" | | `params` 数组为空 | 不显示参数表单区域，直接显示请求体或提示"此接口无需参数" | | 测试请求返回非 200 状态 | 响应结果区域正常显示，status tag 标红，body 正常展示 | | 网络错误/超时 | testResult.display 显示错误信息，status 显示 0 | | JSON 预填充解析失败 | 回退到空字符串 `""` | | 示例值是 JSON 字符串（如 `{"key":"value"}`） | 尝试 JSON.parse，失败则作为字符串处理 | ### 4.4 文件改动清单 | 文件 | 改动内容 | |------|---------| | `web-admin/src/views/endpoint/EndpointList.vue` | 操作列加"测试"按钮，新增 `showTest` 方法 | | `web-admin/src/views/endpoint/EndpointDetailDialog.vue` | 新增 `defaultTab` prop，测试面板改造：参数表单 + JSON 预填充 + 请求头展示 | | `web-admin/src/api/endpoint.ts` | 类型定义无需修改（`operationId` 已存在） | | `backend-single/src/main/java/com/emotion/controller/*.java` | 补全 @Tag/@Operation/@Parameter/@Schema 注解（按 4 个批次） | | `backend-single/src/main/java/com/emotion/dto/request/**/*.java` | 补全 @Schema 注解（请求体参数描述来源） | | `backend-single/src/main/java/com/emotion/dto/response/**/*.java` | 补全 @Schema 注解（响应体参数描述来源，可选） | ## 5. 实施顺序 1. **后端 Batch 1 注解补全** — Auth + Admin 相关 Controller 和 DTO 2. **触发同步 + 验证** — 确认中文描述正确展示 3. **前端操作列加"测试"按钮 + defaultTab** — 简单改动 4. **前端测试面板改造** — 参数表单 + JSON 预填充 + 请求头展示 5. **后端 Batch 2-4 注解补全** — 逐批完成剩余 Controller 6. **浏览器验证** — 打开接口管理页面，确认列表、详情、测试面板均正常 ## 6. 验收标准 - [ ] 接口列表中，每个接口的"简述"列显示有意义的中文描述（非空、非英文路径名） - [ ] 接口详情中，描述字段有中文说明 - [ ] 接口详情中，参数列表的"描述"列有中文说明 - [ ] 操作列有"测试"按钮，点击后打开弹窗并自动切换到测试标签 - [ ] 测试面板中，GET/DELETE 接口的查询参数以表单形式展示（input/select/switch 等），不是空白输入框 - [ ] 测试面板中，POST/PUT 接口的请求体预填充了完整的 JSON 结构（字段名 + 示例值），用户只需改值 - [ ] 请求头区域正确展示 Authorization 和 Content-Type - [ ] 使用当前管理员 token 测试接口时，请求正常发出并返回结果 - [ ] 响应结果区域正确展示状态码、耗时和响应体 - [ ] 枚举值参数渲染为下拉选择框，非枚举值渲染为对应类型的输入框