junhong_cmp_fiber/docs/api-doc-update-summary.md

API 文档自动生成更新总结

📝 更新概述

为了将 B 端认证系统的所有端点包含在自动生成的 OpenAPI 文档中，我们进行了以下更新：

---

🔧 更新内容

1. 路由注册函数更新

文件:

• internal/routes/admin.go
• internal/routes/h5.go

改动：将认证端点从直接注册改为使用 Register 辅助函数，以便生成文档

修改前:

router.Post("/login", h.Login)
router.Post("/refresh-token", h.RefreshToken)

修改后:

Register(router, doc, basePath, "POST", "/login", h.Login, RouteSpec{
    Summary: "后台登录",
    Tags:    []string{"认证"},
    Input:   new(model.LoginRequest),
    Output:  new(model.LoginResponse),
})

新增端点文档（共 10 个）:

• ✅ POST /api/admin/login - 后台登录
• ✅ POST /api/admin/logout - 登出
• ✅ POST /api/admin/refresh-token - 刷新 Token
• ✅ GET /api/admin/me - 获取当前用户信息
• ✅ PUT /api/admin/password - 修改密码
• ✅ POST /api/h5/login - H5 登录
• ✅ POST /api/h5/logout - 登出
• ✅ POST /api/h5/refresh-token - 刷新 Token
• ✅ GET /api/h5/me - 获取当前用户信息
• ✅ PUT /api/h5/password - 修改密码

---

2. OpenAPI 生成器增强

文件: pkg/openapi/generator.go

新增功能: 自动添加 Bearer Token 认证定义

新增代码:

// addBearerAuth 添加 Bearer Token 认证定义
func (g *Generator) addBearerAuth() {
    bearerFormat := "JWT"
    g.Reflector.Spec.ComponentsEns().SecuritySchemesEns().WithMapOfSecuritySchemeOrRefValuesItem(
        "BearerAuth",
        openapi3.SecuritySchemeOrRef{
            SecurityScheme: &openapi3.SecurityScheme{
                HTTPSecurityScheme: &openapi3.HTTPSecurityScheme{
                    Scheme:       "bearer",
                    BearerFormat: &bearerFormat,
                },
            },
        },
    )
}

效果: 在 openapi.yaml 中自动生成：

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

---

3. 文档生成脚本更新

文件: cmd/api/docs.go

新增 Handler:

• ✅ AdminAuth - 后台认证 Handler
• ✅ H5Auth - H5 认证 Handler
• ✅ Shop - 店铺管理 Handler
• ✅ ShopAccount - 店铺账号 Handler

修改前（只有 3 个 Handler）:

accHandler := admin.NewAccountHandler(nil)
roleHandler := admin.NewRoleHandler(nil)
permHandler := admin.NewPermissionHandler(nil)

handlers := &bootstrap.Handlers{
    Account:    accHandler,
    Role:       roleHandler,
    Permission: permHandler,
}

修改后（7 个 Handler）:

adminAuthHandler := admin.NewAuthHandler(nil, nil)
h5AuthHandler := h5.NewAuthHandler(nil, nil)
accHandler := admin.NewAccountHandler(nil)
roleHandler := admin.NewRoleHandler(nil)
permHandler := admin.NewPermissionHandler(nil)
shopHandler := admin.NewShopHandler(nil)
shopAccHandler := admin.NewShopAccountHandler(nil)

handlers := &bootstrap.Handlers{
    AdminAuth:   adminAuthHandler,
    H5Auth:      h5AuthHandler,
    Account:     accHandler,
    Role:        roleHandler,
    Permission:  permHandler,
    Shop:        shopHandler,
    ShopAccount: shopAccHandler,
}

新增路由注册:

// 注册后台路由到文档生成器
adminGroup := app.Group("/api/admin")
routes.RegisterAdminRoutes(adminGroup, handlers, &bootstrap.Middlewares{}, adminDoc, "/api/admin")

// 注册 H5 路由到文档生成器
h5Group := app.Group("/api/h5")
routes.RegisterH5Routes(h5Group, handlers, &bootstrap.Middlewares{}, adminDoc, "/api/h5")

---

📊 生成的文档内容

认证端点示例

1. 后台登录

/api/admin/login:
  post:
    summary: 后台登录
    tags:
      - 认证
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ModelLoginRequest'
    responses:
      "200":
        description: OK
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelLoginResponse'

2. 获取当前用户

/api/admin/me:
  get:
    summary: 获取当前用户信息
    tags:
      - 认证
    responses:
      "200":
        description: OK
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelUserInfo'

请求/响应模型

自动生成的数据模型包括：

• ✅ ModelLoginRequest - 登录请求
• ✅ ModelLoginResponse - 登录响应
• ✅ ModelRefreshTokenRequest - 刷新 Token 请求
• ✅ ModelRefreshTokenResponse - 刷新 Token 响应
• ✅ ModelChangePasswordRequest - 修改密码请求
• ✅ ModelUserInfo - 用户信息

---

🎯 如何使用生成的文档

查看文档

生成的 OpenAPI 文档位于项目根目录：

cat openapi.yaml

使用 Swagger UI 查看

1. 在线工具:

   • 访问 https://editor.swagger.io/
   • 将 openapi.yaml 内容粘贴进去

2. 本地启动 Swagger UI:

   docker run -p 8080:8080 \
     -e SWAGGER_JSON=/openapi.yaml \
     -v $(pwd)/openapi.yaml:/openapi.yaml \
     swaggerapi/swagger-ui
   

   然后访问 http://localhost:8080

导入到 Postman

1. 打开 Postman
2. 点击 "Import"
3. 选择 openapi.yaml 文件
4. 自动生成所有 API 请求集合

---

🔄 文档生成流程

自动生成

文档在每次启动 API 服务时自动生成：

// cmd/api/main.go
func main() {
    // ...
    
    // 12. 生成 OpenAPI 文档
    generateOpenAPIDocs("./openapi.yaml", appLogger)
    
    // 13. 启动服务器
    startServer(app, cfg, appLogger, cancelWatch)
}

手动生成

如果只想生成文档而不启动服务：

# 编译
go build -o /tmp/api_docs ./cmd/api/

# 运行并立即停止（文档会在启动时生成）
timeout 3s /tmp/api_docs || true

# 查看生成的文档
cat openapi.yaml

---

🎨 文档分类（Tags）

生成的文档按以下标签分类：

• 认证 - 所有认证相关端点（登录、登出、刷新等）
• H5 认证 - H5 端认证端点
• 账号相关 - 账号管理（CRUD、角色分配等）
• 角色 - 角色管理
• 权限 - 权限管理
• 店铺 - 店铺管理
• 店铺账号 - 店铺账号管理

---

✅ 验证清单

• 所有认证端点已包含在文档中
• Bearer Token 认证方式已定义
• 请求/响应模型完整
• 端点描述清晰（中文 Summary）
• 端点按标签正确分类
• 后台和 H5 端点都已包含

---

📌 注意事项

1. 文档与实际路由同步

由于使用了统一的 Register 函数，所有注册的路由都会自动出现在文档中。 确保不会出现文档与实际路由不一致的情况。

2. nil 依赖 Handler

文档生成时使用 nil 依赖创建 Handler：

adminAuthHandler := admin.NewAuthHandler(nil, nil)

这是安全的，因为文档生成只需要路由结构，不会实际执行 Handler 逻辑。

3. 安全认证标记

目前文档中的 BearerAuth 安全方案已定义，但未自动标记哪些端点需要认证。

未来改进（可选）: 可以在 RouteSpec 中添加 RequireAuth bool 字段，自动为需要认证的端点添加：

security:
  - BearerAuth: []

---

🔮 后续可能的改进

1. 错误响应文档

当前只定义了 200 成功响应，可以添加错误响应：

// 在 RouteSpec 中添加
type RouteSpec struct {
    Summary     string
    Tags        []string
    Input       interface{}
    Output      interface{}
    ErrorOutput interface{}  // 新增
}

2. 安全端点标记

为需要认证的端点自动添加安全要求：

// 在 AddOperation 中添加逻辑
if spec.RequireAuth {
    op.Security = []openapi3.SecurityRequirement{
        {"BearerAuth": []string{}},
    }
}

3. 示例值

为请求/响应添加示例值，便于前端开发者理解：

examples:
  LoginExample:
    value:
      username: "admin"
      password: "Admin@123456"

---

📖 相关文档

• API 文档 - 手写的详细 API 文档
• 使用指南 - 认证系统使用指南
• 架构说明 - 认证系统架构设计

---

总结

通过这次更新，我们实现了：

1. ✅ 认证端点完整性 - 所有 10 个认证端点都已包含
2. ✅ 安全定义 - Bearer Token 认证方式已定义
3. ✅ 自动同步 - 路由与文档自动保持一致
4. ✅ 易于维护 - 使用统一的 Register 函数

OpenAPI 文档现在已经完整，可以直接用于前端开发、API 测试和文档展示！ 🎉