junhong_cmp_fiber/docs/openapi-enhancement-summary.md

# OpenAPI 文档增强总结

## 更新日期
2026-01-15

## 增强内容

### 1. 自动认证标记

为所有需要认证的端点自动添加 `security` 标记。

**实现方式**：
- 在 `RouteSpec` 中使用 `Auth: true` 字段标记需要认证的端点
- `Register` 函数自动传递 `Auth` 字段到 OpenAPI 生成器
- 生成器自动添加 `security: [BearerAuth: []]` 到操作定义

**示例**：

公开端点（`Auth: false`）：
```yaml
/api/admin/login:
  post:
    summary: 后台登录
    # 无 security 字段
```

认证端点（`Auth: true`）：
```yaml
/api/admin/logout:
  post:
    summary: 登出
    security:
      - BearerAuth: []
```

### 2. 标准错误响应

为所有端点自动添加标准错误响应。

**错误响应规则**：
- **所有端点**：400 (请求参数错误), 500 (服务器内部错误)
- **认证端点**：额外添加 401 (未认证或认证已过期), 403 (无权访问)

**ErrorResponse Schema**：
```yaml
ErrorResponse:
  type: object
  required:
    - code
    - message
    - timestamp
  properties:
    code:
      type: integer
      description: 错误码
    message:
      type: string
      description: 错误消息
    timestamp:
      type: string
      format: date-time
      description: 时间戳
```

**示例**：

公开端点错误响应：
```yaml
responses:
  "200":
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ModelLoginResponse'
  "400":
    description: 请求参数错误
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  "500":
    description: 服务器内部错误
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
```

认证端点错误响应：
```yaml
responses:
  "200":
    description: OK
  "400":
    description: 请求参数错误
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  "401":
    description: 未认证或认证已过期
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  "403":
    description: 无权访问
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  "500":
    description: 服务器内部错误
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
```

### 3. Bearer Token 认证定义

在 OpenAPI 规范中添加 Bearer Token 认证方案定义。

```yaml
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

## 修改的文件

### 核心文件

1. **pkg/openapi/generator.go**
   - 修改 `AddOperation` 方法，新增 `requiresAuth` 参数
   - 新增 `addSecurityRequirement` 方法：为操作添加认证要求
   - 新增 `addStandardErrorResponses` 方法：添加标准错误响应
   - 新增 `addErrorResponseSchema` 方法：添加错误响应 Schema 定义
   - 新增 `ptrString` 辅助函数

2. **internal/routes/registry.go**
   - 更新 `Register` 函数，传递 `spec.Auth` 到生成器

### 路由注册文件

更新以下文件中的 `RouteSpec`，为所有端点添加 `Auth` 字段：

1. **internal/routes/admin.go**
   - 公开端点（login, refresh-token）：`Auth: false`
   - 认证端点（logout, me, password）：`Auth: true`

2. **internal/routes/h5.go**
   - 公开端点（login, refresh-token）：`Auth: false`
   - 认证端点（logout, me, password）：`Auth: true`

3. **internal/routes/account.go**
   - 所有账号管理端点：`Auth: true` (17 个端点)

4. **internal/routes/role.go**
   - 所有角色管理端点：`Auth: true` (9 个端点)

5. **internal/routes/permission.go**
   - 所有权限管理端点：`Auth: true` (6 个端点)

### 文档生成脚本

**cmd/gendocs/main.go**
- 添加 `AdminAuth` Handler 到 handlers 结构体
- 确保认证端点包含在生成的文档中

## 验证结果

### 1. 编译验证
```bash
✅ go build ./... - 编译通过
✅ go build ./pkg/openapi/... - OpenAPI 包编译通过
✅ go build ./internal/routes/... - 路由包编译通过
```

### 2. 文档生成验证
```bash
✅ CONFIG_ENV=dev go run cmd/gendocs/main.go
✅ 文档生成成功：docs/admin-openapi.yaml
✅ 包含所有端点（认证 + 业务端点）
```

### 3. 内容验证

**Security Scheme**：
```bash
✅ grep "securitySchemes:" docs/admin-openapi.yaml
✅ BearerAuth 定义存在
```

**ErrorResponse Schema**：
```bash
✅ grep "ErrorResponse:" docs/admin-openapi.yaml
✅ 包含 code, message, timestamp 字段
✅ Required 字段定义正确
```

**公开端点（login）**：
```bash
✅ 只有 400, 500 错误响应
✅ 没有 security 标记
✅ 没有 401, 403 错误响应
```

**认证端点（logout）**：
```bash
✅ 有 400, 401, 403, 500 错误响应
✅ 有 security: [BearerAuth: []]
✅ 错误响应引用 ErrorResponse schema
```

## 使用方法

### 1. 注册新端点

在路由注册时，显式设置 `Auth` 字段：

```go
// 公开端点
Register(router, doc, basePath, "POST", "/public", handler, RouteSpec{
    Summary: "公开端点",
    Tags:    []string{"公开"},
    Input:   new(RequestModel),
    Output:  new(ResponseModel),
    Auth:    false,  // 不需要认证
})

// 认证端点
Register(authGroup, doc, basePath, "GET", "/protected", handler, RouteSpec{
    Summary: "受保护端点",
    Tags:    []string{"业务"},
    Input:   nil,
    Output:  new(ResponseModel),
    Auth:    true,  // 需要认证
})
```

### 2. 生成文档

```bash
# 开发环境
CONFIG_ENV=dev go run cmd/gendocs/main.go

# 生产环境
CONFIG_ENV=prod go run cmd/gendocs/main.go
```

生成的文档位于 `docs/admin-openapi.yaml`。

### 3. 查看文档

**方法 1：使用 Swagger UI**
```bash
# 访问 https://editor.swagger.io/
# 将 docs/admin-openapi.yaml 内容粘贴到编辑器
```

**方法 2：使用 Postman**
```bash
# File → Import → Upload Files
# 选择 docs/admin-openapi.yaml
```

**方法 3：使用 Redoc**
```bash
npx @redocly/cli preview-docs docs/admin-openapi.yaml
```

## 后续优化（可选）

当前已完成的高优先级任务：
- ✅ 自动添加 security 标记
- ✅ 自动添加标准错误响应
- ✅ 定义 ErrorResponse schema
- ✅ 更新所有路由注册

低优先级增强（可在后续迭代完成）：
- [ ] 为请求/响应模型添加示例值（example）
- [ ] 为字段添加详细的验证规则说明（自动从 validator 标签提取）

这些低优先级功能不影响当前文档的可用性，可以根据需要在后续版本中添加。

## 影响范围

**破坏性变更**：无

**向后兼容**：是
- 旧代码不需要修改即可工作
- 未设置 `Auth` 字段的 RouteSpec 默认为 `false`（公开端点）

**API 变更**：无
- 只影响 OpenAPI 文档生成
- 不影响运行时行为

## 总结

本次增强为 OpenAPI 文档自动生成系统添加了以下关键功能：

1. **自动认证标记**：通过 `Auth` 字段自动为认证端点添加 `security` 标记
2. **标准错误响应**：自动为所有端点添加统一的错误响应定义
3. **错误响应 Schema**：定义了标准的 `ErrorResponse` 结构

这些增强使得：
- 文档更加完整和规范
- API 使用者能清楚了解哪些端点需要认证
- 错误处理文档化，提升 API 可用性
- 减少手动维护文档的工作量

所有高优先级功能已完成并验证通过，可以投入使用。