103 lines
3.2 KiB
Markdown
103 lines
3.2 KiB
Markdown
# OpenAPI 同步报告
|
|
|
|
生成时间: 2025-11-10
|
|
|
|
## ✅ 已完成的工作
|
|
|
|
### 1. OpenAPI 规范验证
|
|
- ✅ 使用 Docker 版本的 OpenAPI Generator (v7.17.0)
|
|
- ✅ 验证了 `backend/docs/openapi.yaml` 规范文件
|
|
- ✅ 规范文件无错误，验证通过
|
|
|
|
### 2. 前端客户端代码生成
|
|
- ✅ 使用 typescript-axios 生成器
|
|
- ✅ 生成位置: `frontend/src/api/generated/`
|
|
- ✅ 生成内容:
|
|
- 7 个 API 接口文件 (artifacts, auth, clusters, health, instances, monitoring, registries)
|
|
- 26 个模型文件 (所有请求/响应类型)
|
|
- 配置和基础文件 (base.ts, configuration.ts, common.ts等)
|
|
|
|
### 3. 依赖安装
|
|
- ✅ 安装了生成代码所需的 npm 依赖
|
|
|
|
### 4. 类型定义修复
|
|
- ✅ 添加了缺失的 `ValuesSchemaResponse` 类型定义
|
|
- ✅ 修复了 `artifact.api.ts` 中的类型导出问题
|
|
- ✅ 更新了 `getValuesSchema` 函数的返回类型
|
|
|
|
## 📊 生成的文件统计
|
|
|
|
### API 接口文件 (7个)
|
|
- `api/artifacts-api.ts` - Artifact 相关 API
|
|
- `api/auth-api.ts` - 认证相关 API
|
|
- `api/clusters-api.ts` - 集群管理 API
|
|
- `api/health-api.ts` - 健康检查 API
|
|
- `api/instances-api.ts` - 实例管理 API
|
|
- `api/monitoring-api.ts` - 监控 API
|
|
- `api/registries-api.ts` - Registry 管理 API
|
|
|
|
### 模型文件 (26个)
|
|
包括所有的请求和响应类型，如:
|
|
- ArtifactListItem, ArtifactResponse
|
|
- ClusterResponse, CreateClusterRequest, UpdateClusterRequest
|
|
- RegistryResponse, CreateRegistryRequest, UpdateRegistryRequest
|
|
- InstanceResponse, CreateInstanceRequest, UpdateInstanceRequest
|
|
- AuthResponse, LoginRequest, RegisterRequest
|
|
- 等等...
|
|
|
|
## ⚠️ 已知的非关键问题
|
|
|
|
以下文件中存在一些类型不匹配的问题，但不影响核心功能:
|
|
|
|
1. **Mock 客户端 (`src/api/client.ts`)** - 25 个类型错误
|
|
- 这是用于开发模式的 Mock 客户端
|
|
- 需要更新以匹配新的 OpenAPI 类型
|
|
|
|
2. **示例代码 (`src/api/examples.ts`)** - 4 个类型错误
|
|
- 示例/测试代码
|
|
- 需要更新以匹配新的 API 签名
|
|
|
|
3. **组件中的可选属性处理** - 8 个类型错误
|
|
- 一些组件需要添加可选链操作符或空值检查
|
|
- 位于: RegistryTreeExplorer, RepositoryItem, TagCard
|
|
|
|
## 🔧 建议的后续步骤
|
|
|
|
### 短期 (可选)
|
|
1. 修复 Mock 客户端的类型错误，如果需要使用 Mode 0 (Mock 模式) 进行开发
|
|
2. 更新示例代码以匹配新的 API 签名
|
|
3. 添加空值检查到相关组件
|
|
|
|
### 长期
|
|
1. 建立自动化的 OpenAPI 同步流程
|
|
```bash
|
|
# 使用项目 Makefile
|
|
make openapi-gen-frontend
|
|
```
|
|
2. 在 CI/CD 中添加 OpenAPI 规范验证步骤
|
|
|
|
## 📝 使用新生成的 API 客户端
|
|
|
|
```typescript
|
|
// 导入生成的 API
|
|
import { ArtifactsApi, ClustersApi, RegistriesApi } from '@/api/generated/api';
|
|
import type { ClusterResponse, CreateClusterRequest } from '@/api/generated/models';
|
|
|
|
// 创建 API 实例
|
|
const clustersApi = new ClustersApi();
|
|
|
|
// 使用 API
|
|
const clusters: ClusterResponse[] = await clustersApi.listClusters();
|
|
```
|
|
|
|
## 📚 参考文档
|
|
|
|
- OpenAPI 规范: `backend/docs/openapi.yaml`
|
|
- 生成的 API 文档: `frontend/src/api/generated/docs/`
|
|
- 项目 Makefile: 根目录的 `Makefile` (包含 `openapi-gen-frontend` 命令)
|
|
|
|
---
|
|
|
|
生成工具: OpenAPI Generator v7.17.0
|
|
生成器: typescript-axios
|