325 lines
8.4 KiB
Markdown
325 lines
8.4 KiB
Markdown
# Code First API 开发指南
|
||
|
||
## 🎯 概述
|
||
|
||
本项目现已支持 **Code First** 方式开发 API：
|
||
1. **后端**：使用 Swagger 注释从代码生成 OpenAPI 文档
|
||
2. **前端**：使用 Orval 从 OpenAPI 文档生成 TypeScript 客户端
|
||
|
||
---
|
||
|
||
## 🛠️ 工具链
|
||
|
||
### 后端
|
||
- **swaggo/swag**: 从 Go 代码注释生成 OpenAPI/Swagger 文档
|
||
- 文档：https://github.com/swaggo/swag
|
||
|
||
### 前端
|
||
- **Orval**: 从 OpenAPI 规范生成 TypeScript API 客户端
|
||
- 文档：https://orval.dev/
|
||
|
||
---
|
||
|
||
## 📝 开发流程
|
||
|
||
### 1. 后端：添加 Swagger 注释
|
||
|
||
#### 主程序注释 (cmd/api/main.go)
|
||
```go
|
||
// @title OCDP Backend API
|
||
// @version 1.0
|
||
// @description OCDP (Open Cloud Development Platform) Backend API
|
||
//
|
||
// @host localhost:8080
|
||
// @BasePath /api/v1
|
||
//
|
||
// @securityDefinitions.apikey BearerAuth
|
||
// @in header
|
||
// @name Authorization
|
||
package main
|
||
```
|
||
|
||
#### Handler 方法注释示例
|
||
```go
|
||
// ListArtifacts 列出 repository 中的所有 artifacts
|
||
// @Summary 列出 Repository 中的所有 Artifacts
|
||
// @Description 列出指定 Repository 中的所有 Artifact，支持按类型过滤
|
||
// @Tags Artifacts
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Param registry_id path string true "Registry ID"
|
||
// @Param repository_name path string true "Repository Name (URL encoded)"
|
||
// @Param media_type query string false "过滤类型 (all, chart, image, other)" default(all)
|
||
// @Success 200 {array} dto.TagResponse
|
||
// @Failure 500 {object} dto.ErrorResponse
|
||
// @Router /registries/{registry_id}/repositories/{repository_name}/artifacts [get]
|
||
func (h *ArtifactHandler) ListArtifacts(w http.ResponseWriter, r *http.Request) {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### 2. 生成 OpenAPI 文档
|
||
|
||
```bash
|
||
# 在 backend 目录下运行
|
||
cd backend
|
||
swag init -g cmd/api/main.go -o docs/swagger --parseDependency --parseInternal
|
||
|
||
# 生成的文件在 docs/swagger/ 目录:
|
||
# - swagger.json
|
||
# - swagger.yaml
|
||
# - docs.go
|
||
```
|
||
|
||
### 3. 前端：重新生成 API 客户端
|
||
|
||
```bash
|
||
# 在 frontend 目录下运行
|
||
cd frontend
|
||
npm run openapi-gen
|
||
|
||
# 或者
|
||
orval
|
||
```
|
||
|
||
生成的文件在 `src/api/generated-orval/` 目录。
|
||
|
||
---
|
||
|
||
## 🔄 完整工作流
|
||
|
||
### 添加新 API 的步骤
|
||
|
||
#### 1. 后端开发
|
||
```bash
|
||
# 1.1 创建 DTO
|
||
# internal/adapter/input/http/dto/new_feature_dto.go
|
||
|
||
# 1.2 创建 Handler 并添加 Swagger 注释
|
||
# internal/adapter/input/http/rest/new_feature_handler.go
|
||
|
||
# 1.3 注册路由
|
||
# cmd/api/main.go
|
||
|
||
# 1.4 生成 OpenAPI 文档
|
||
cd backend
|
||
swag init -g cmd/api/main.go -o docs/swagger --parseDependency --parseInternal
|
||
|
||
# 1.5 复制到主文档 (可选)
|
||
cp docs/swagger/swagger.yaml docs/openapi.yaml
|
||
```
|
||
|
||
#### 2. 前端开发
|
||
```bash
|
||
# 2.1 重新生成 API 客户端
|
||
cd frontend
|
||
npm run openapi-gen
|
||
|
||
# 2.2 使用生成的客户端
|
||
import { listArtifacts } from '@/api/generated-orval/api';
|
||
|
||
const data = await listArtifacts({
|
||
registryId: 'xxx',
|
||
repositoryName: 'charts/nginx'
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 Swagger 注释速查
|
||
|
||
### 常用标签
|
||
|
||
| 标签 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `@Summary` | 简短描述 | `@Summary 列出所有用户` |
|
||
| `@Description` | 详细描述 | `@Description 返回系统中的所有用户列表` |
|
||
| `@Tags` | API 分组 | `@Tags Users` |
|
||
| `@Accept` | 接受的格式 | `@Accept json` |
|
||
| `@Produce` | 返回的格式 | `@Produce json` |
|
||
| `@Param` | 参数 | `@Param id path string true "User ID"` |
|
||
| `@Success` | 成功响应 | `@Success 200 {object} dto.UserResponse` |
|
||
| `@Failure` | 失败响应 | `@Failure 404 {object} dto.ErrorResponse` |
|
||
| `@Router` | 路由定义 | `@Router /users/{id} [get]` |
|
||
| `@Security` | 安全认证 | `@Security BearerAuth` |
|
||
|
||
### 参数类型
|
||
|
||
```go
|
||
// 路径参数 (path)
|
||
@Param id path string true "User ID"
|
||
|
||
// 查询参数 (query)
|
||
@Param page query int false "Page number" default(1)
|
||
@Param size query int false "Page size" default(20)
|
||
|
||
// 请求体 (body)
|
||
@Param request body dto.CreateUserRequest true "User data"
|
||
|
||
// Header 参数 (header)
|
||
@Param X-Request-ID header string false "Request ID"
|
||
```
|
||
|
||
### 响应定义
|
||
|
||
```go
|
||
// 单个对象
|
||
@Success 200 {object} dto.UserResponse
|
||
|
||
// 数组
|
||
@Success 200 {array} dto.UserResponse
|
||
|
||
// 自定义响应
|
||
@Success 200 {object} map[string]interface{}
|
||
|
||
// 多个可能的响应
|
||
@Success 200 {object} dto.UserResponse "Success"
|
||
@Success 201 {object} dto.UserResponse "Created"
|
||
@Failure 400 {object} dto.ErrorResponse "Bad Request"
|
||
@Failure 404 {object} dto.ErrorResponse "Not Found"
|
||
@Failure 500 {object} dto.ErrorResponse "Internal Error"
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 命名规范
|
||
|
||
| 层级 | 风格 | 示例 |
|
||
|------|------|------|
|
||
| **路径变量** | snake_case | `{registry_id}`, `{repository_name}` |
|
||
| **查询参数** | snake_case | `?media_type=chart` |
|
||
| **JSON 字段** | camelCase | `repositoryName`, `mediaType` |
|
||
| **Go 结构体** | PascalCase | `RepositoryName`, `MediaType` |
|
||
|
||
### 2. DTO 定义示例
|
||
|
||
```go
|
||
// ArtifactResponse Artifact 响应
|
||
type ArtifactResponse struct {
|
||
RepositoryName string `json:"repositoryName"` // Go: PascalCase, JSON: camelCase
|
||
Tag string `json:"tag"`
|
||
Type string `json:"type"`
|
||
Size int64 `json:"size"`
|
||
CreatedAt string `json:"createdAt"`
|
||
}
|
||
```
|
||
|
||
### 3. 完整的 Handler 示例
|
||
|
||
```go
|
||
// GetArtifact 获取 artifact 详情
|
||
// @Summary 获取 Artifact 详情
|
||
// @Description 获取指定 Artifact 的详细信息
|
||
// @Tags Artifacts
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Param registry_id path string true "Registry ID"
|
||
// @Param repository_name path string true "Repository Name (URL encoded)"
|
||
// @Param reference path string true "Artifact Reference (tag or digest)"
|
||
// @Success 200 {object} dto.ArtifactResponse
|
||
// @Failure 404 {object} dto.ErrorResponse "Artifact not found"
|
||
// @Failure 500 {object} dto.ErrorResponse "Internal server error"
|
||
// @Router /registries/{registry_id}/repositories/{repository_name}/artifacts/{reference} [get]
|
||
func (h *ArtifactHandler) GetArtifact(w http.ResponseWriter, r *http.Request) {
|
||
vars := mux.Vars(r)
|
||
registryID := vars["registry_id"]
|
||
repositoryName := vars["repository_name"]
|
||
reference := vars["reference"]
|
||
|
||
artifact, err := h.artifactService.GetArtifact(r.Context(), registryID, repositoryName, reference)
|
||
if err != nil {
|
||
respondError(w, http.StatusNotFound, "Artifact not found", err.Error())
|
||
return
|
||
}
|
||
|
||
response := &dto.ArtifactResponse{
|
||
RepositoryName: artifact.Repository,
|
||
Tag: artifact.Tag,
|
||
Digest: artifact.Digest,
|
||
Type: string(artifact.Type),
|
||
Size: artifact.Size,
|
||
CreatedAt: artifact.CreatedAt.Format("2006-01-02T15:04:05Z07:00"),
|
||
}
|
||
|
||
respondJSON(w, http.StatusOK, response)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 问题 1: swag 命令未找到
|
||
```bash
|
||
# 解决方案：安装 swag
|
||
go install github.com/swaggo/swag/cmd/swag@latest
|
||
|
||
# 确保 $GOPATH/bin 在 PATH 中
|
||
export PATH=$PATH:$(go env GOPATH)/bin
|
||
```
|
||
|
||
### 问题 2: 生成的文档不完整
|
||
```bash
|
||
# 确保使用了正确的参数
|
||
swag init -g cmd/api/main.go -o docs/swagger --parseDependency --parseInternal
|
||
|
||
# 检查注释格式是否正确
|
||
# 注释必须紧邻函数定义，中间不能有空行
|
||
```
|
||
|
||
### 问题 3: 前端客户端生成失败
|
||
```bash
|
||
# 检查 OpenAPI 文档是否有效
|
||
cd frontend
|
||
npx @apidevtools/swagger-cli validate ../backend/docs/openapi.yaml
|
||
|
||
# 清理并重新生成
|
||
rm -rf src/api/generated-orval
|
||
npm run openapi-gen
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 参考资源
|
||
|
||
- **Swaggo 文档**: https://github.com/swaggo/swag
|
||
- **Swaggo 声明式注释**: https://github.com/swaggo/swag#declarative-comments-format
|
||
- **Orval 文档**: https://orval.dev/
|
||
- **OpenAPI 规范**: https://swagger.io/specification/
|
||
|
||
---
|
||
|
||
## ✅ 当前状态
|
||
|
||
### 已完成
|
||
- [x] 安装 swag 工具
|
||
- [x] 添加主程序 Swagger 注释
|
||
- [x] 为 Artifact Handler 添加完整注释
|
||
- [x] 生成 OpenAPI 文档
|
||
- [x] 前端配置 Orval
|
||
- [x] 重新生成前端客户端
|
||
|
||
### 待完成 (可选)
|
||
- [ ] 为其他 Handler 添加 Swagger 注释
|
||
- [ ] Auth Handler
|
||
- [ ] Cluster Handler
|
||
- [ ] Registry Handler
|
||
- [ ] Instance Handler
|
||
- [ ] Monitoring Handler
|
||
- [ ] 添加更详细的错误响应定义
|
||
- [ ] 添加请求/响应示例
|
||
- [ ] 配置 CI/CD 自动生成文档
|
||
|
||
---
|
||
|
||
## 🎉 总结
|
||
|
||
现在项目支持 Code First 开发流程：
|
||
1. **后端开发者**：写代码 + 注释 → 生成 OpenAPI
|
||
2. **前端开发者**：使用 OpenAPI → 生成 TypeScript 客户端
|
||
3. **文档自动同步**：代码即文档，保证一致性
|
||
|
||
这确保了 API 文档始终与代码保持同步！✨
|