junhong_cmp_fiber/docs/openapi-enhancement-summary.md

OpenAPI 文档增强总结

更新日期

2026-01-15

增强内容

1. 自动认证标记

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

实现方式：

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

示例：

公开端点（Auth: false）：

/api/admin/login:
  post:
    summary: 后台登录
    # 无 security 字段

认证端点（Auth: true）：

/api/admin/logout:
  post:
    summary: 登出
    security:
      - BearerAuth: []

2. 标准错误响应

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

错误响应规则：

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

ErrorResponse Schema：

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

示例：

公开端点错误响应：

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'

认证端点错误响应：

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 认证方案定义。

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. 编译验证

✅ go build ./... - 编译通过
✅ go build ./pkg/openapi/... - OpenAPI 包编译通过
✅ go build ./internal/routes/... - 路由包编译通过

2. 文档生成验证

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

3. 内容验证

Security Scheme：

✅ grep "securitySchemes:" docs/admin-openapi.yaml
✅ BearerAuth 定义存在

ErrorResponse Schema：

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

公开端点（login）：

✅ 只有 400, 500 错误响应
✅ 没有 security 标记
✅ 没有 401, 403 错误响应

认证端点（logout）：

✅ 有 400, 401, 403, 500 错误响应
✅ 有 security: [BearerAuth: []]
✅ 错误响应引用 ErrorResponse schema

使用方法

1. 注册新端点

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

// 公开端点
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. 生成文档

# 开发环境
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

# 访问 https://editor.swagger.io/
# 将 docs/admin-openapi.yaml 内容粘贴到编辑器

方法 2：使用 Postman

# File → Import → Upload Files
# 选择 docs/admin-openapi.yaml

方法 3：使用 Redoc

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 可用性
• 减少手动维护文档的工作量

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