huang
18f35f3ef4
主要变更： - 新增B端认证系统（后台+H5）：登录、登出、Token刷新、密码修改 - 完善商户管理和商户账号管理功能 - 补全单元测试（ShopService: 72.5%, ShopAccountService: 79.8%） - 新增集成测试（商户管理+商户账号管理） - 归档OpenSpec提案（add-shop-account-management, implement-b-end-auth-system） - 完善文档（使用指南、API文档、认证架构说明） 测试统计： - 13个测试套件，37个测试用例，100%通过率 - 平均覆盖率76.2%，达标 OpenSpec验证：通过（strict模式）
381 lines
8.7 KiB
Markdown
381 lines
8.7 KiB
Markdown
# 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 测试和文档展示！** 🎉
|