# API 文档自动生成更新总结

## 📝 更新概述

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

---

## 🔧 更新内容

### 1. **路由注册函数更新**

**文件**: 
- `internal/routes/admin.go`
- `internal/routes/h5.go`

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

**修改前**:
```go
router.Post("/login", h.Login)
router.Post("/refresh-token", h.RefreshToken)
```

**修改后**:
```go
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 认证定义

**新增代码**:
```go
// 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` 中自动生成：

```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）:
```go
accHandler := admin.NewAccountHandler(nil)
roleHandler := admin.NewRoleHandler(nil)
permHandler := admin.NewPermissionHandler(nil)

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

**修改后**（7 个 Handler）:
```go
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,
}
```

**新增路由注册**:
```go
// 注册后台路由到文档生成器
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. 后台登录
```yaml
/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. 获取当前用户
```yaml
/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 文档位于项目根目录：
```bash
cat openapi.yaml
```

### 使用 Swagger UI 查看

1. **在线工具**:
   - 访问 https://editor.swagger.io/
   - 将 `openapi.yaml` 内容粘贴进去

2. **本地启动 Swagger UI**:
   ```bash
   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 服务时自动生成：

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

### 手动生成

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

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

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

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

---

## 🎨 文档分类（Tags）

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

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

---

## ✅ 验证清单

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

---

## 📌 注意事项

### 1. **文档与实际路由同步**

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

### 2. **nil 依赖 Handler**

文档生成时使用 `nil` 依赖创建 Handler：
```go
adminAuthHandler := admin.NewAuthHandler(nil, nil)
```

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

### 3. **安全认证标记**

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

**未来改进**（可选）:
可以在 `RouteSpec` 中添加 `RequireAuth bool` 字段，自动为需要认证的端点添加：
```yaml
security:
  - BearerAuth: []
```

---

## 🔮 后续可能的改进

### 1. **错误响应文档**

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

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

### 2. **安全端点标记**

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

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

### 3. **示例值**

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

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

---

## 📖 相关文档

- [API 文档](docs/api/auth.md) - 手写的详细 API 文档
- [使用指南](docs/auth-usage-guide.md) - 认证系统使用指南
- [架构说明](docs/auth-architecture.md) - 认证系统架构设计

---

## 总结

通过这次更新，我们实现了：
1. ✅ **认证端点完整性** - 所有 10 个认证端点都已包含
2. ✅ **安全定义** - Bearer Token 认证方式已定义
3. ✅ **自动同步** - 路由与文档自动保持一致
4. ✅ **易于维护** - 使用统一的 Register 函数

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