docs: 整理文档结构并创建索引（任务 2.3/20）

2026-04-12 16:24:51 +08:00
parent 1f52d47ed5
commit 5cd7d48bf2
33 changed files with 1140 additions and 1176 deletions
@@ -0,0 +1,466 @@
+# OpenAPI文档使用指南
+
+## 概述
+
+OpenAPI（原名Swagger）是一个用于描述、生成、消费和可视化RESTful Web服务的规范。本项目已集成OpenAPI文档，提供交互式API文档界面。
+
+## 访问文档
+
+### 开发环境
+
+启动开发服务器后，访问：
+
+```
+http://localhost:3000/api-docs
+```
+
+### 生产环境
+
+部署后访问：
+
+```
+https://your-domain.com/api-docs
+```
+
+## 文档结构
+
+### API端点
+
+| 端点 | 方法 | 描述 | 认证 |
+|------|------|------|------|
+| `/api/health` | GET | 健康检查 | 无 |
+| `/api/admin/content` | GET | 获取内容列表 | 需要管理员权限 |
+| `/api/admin/content` | POST | 创建新内容 | 需要管理员权限 |
+
+### 数据模型
+
+#### Content（内容）
+
+```typescript
+interface Content {
+  id: number;
+  type: 'news' | 'case' | 'product' | 'service';
+  title: string;
+  content: string;
+  status: 'draft' | 'published' | 'archived';
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+#### User（用户）
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  role: 'admin' | 'editor' | 'viewer';
+}
+```
+
+#### Config（配置）
+
+```typescript
+interface Config {
+  key: string;
+  value: string;
+  description: string;
+}
+```
+
+## 使用Swagger UI
+
+### 浏览API
+
+1. 访问 `/api-docs`
+2. 点击任意API端点展开详情
+3. 查看请求参数、响应格式和示例
+
+### 测试API
+
+#### 无需认证的API
+
+1. 点击"Try it out"按钮
+2. 填写必要参数
+3. 点击"Execute"执行请求
+4. 查看响应结果
+
+示例：健康检查API
+
+```bash
+curl -X GET "http://localhost:3000/api/health" -H "accept: application/json"
+```
+
+#### 需要认证的API
+
+1. 先登录获取访问令牌
+2. 点击页面右上角的"Authorize"按钮
+3. 输入Bearer令牌：`Bearer your-access-token`
+4. 点击"Authorize"确认
+5. 现在可以测试需要认证的API
+
+示例：获取内容列表
+
+```bash
+curl -X GET "http://localhost:3000/api/admin/content?page=1&limit=20" \
+  -H "accept: application/json" \
+  -H "Authorization: Bearer your-access-token"
+```
+
+## 为API添加文档
+
+### 步骤1：添加JSDoc注释
+
+在API路由文件中添加JSDoc注释：
+
+```typescript
+/**
+ * @openapi
+ * /api/your-endpoint:
+ *   get:
+ *     tags:
+ *       - YourTag
+ *     summary: 简短描述
+ *     description: 详细描述
+ *     operationId: getYourData
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: 成功响应
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                 data:
+ *                   type: object
+ */
+export async function GET(request: NextRequest) {
+  // API实现
+}
+```
+
+### 步骤2：定义请求体
+
+对于POST/PUT请求：
+
+```typescript
+/**
+ * @openapi
+ * /api/your-endpoint:
+ *   post:
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - name
+ *               - email
+ *             properties:
+ *               name:
+ *                 type: string
+ *               email:
+ *                 type: string
+ *                 format: email
+ */
+```
+
+### 步骤3：引用共享Schema
+
+使用`$ref`引用共享数据模型：
+
+```typescript
+/**
+ * @openapi
+ * /api/admin/content:
+ *   get:
+ *     responses:
+ *       200:
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Content'
+ */
+```
+
+## OpenAPI规范文件
+
+### 获取规范文件
+
+访问以下端点获取原始OpenAPI规范：
+
+```
+GET /api/docs
+```
+
+### 使用规范文件
+
+1. **导入到Postman**
+   - 打开Postman
+   - 点击"Import"
+   - 选择"Link"
+   - 输入：`http://localhost:3000/api/docs`
+   - 点击"Import"
+
+2. **生成客户端代码**
+   - 使用OpenAPI Generator
+   - 支持多种语言：TypeScript, Python, Java等
+
+3. **API测试**
+   - 导入到测试工具
+   - 自动生成测试用例
+
+## 最佳实践
+
+### ✅ 推荐做法
+
+1. **完整的描述**
+   - 提供清晰的summary和description
+   - 说明参数的作用和限制
+   - 提供示例值
+
+2. **准确的类型定义**
+   - 使用正确的数据类型
+   - 标注必填字段
+   - 定义枚举值
+
+3. **完整的响应定义**
+   - 定义所有可能的响应状态码
+   - 提供错误响应格式
+   - 包含示例数据
+
+4. **合理的标签分组**
+   - 按功能模块分组
+   - 使用一致的命名
+   - 避免过多标签
+
+### ❌ 避免的做法
+
+1. **不要省略错误响应**
+   ```typescript
+   // ❌ 不好
+   responses:
+ *     200:
+ *       description: 成功
+
+   // ✅ 好
+   responses:
+ *     200:
+ *       description: 成功
+ *     400:
+ *       description: 参数错误
+ *     401:
+ *       description: 未授权
+ *     500:
+ *       description: 服务器错误
+   ```
+
+2. **不要使用模糊的描述**
+   ```typescript
+   // ❌ 不好
+   summary: 获取数据
+
+   // ✅ 好
+   summary: 获取内容列表
+   description: 管理员获取内容列表，支持分页、筛选和搜索
+   ```
+
+3. **不要忽略认证要求**
+   ```typescript
+   // ✅ 始终标注认证要求
+   security:
+ *   - bearerAuth: []
+   ```
+
+## 高级功能
+
+### 添加示例
+
+```typescript
+/**
+ * @openapi
+ * /api/admin/content:
+ *   post:
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           examples:
+ *             newsExample:
+ *               summary: 新闻示例
+ *               value:
+ *                 type: news
+ *                 title: 新闻标题
+ *                 content: 新闻内容
+ */
+```
+
+### 添加标签描述
+
+在`/api/docs/route.ts`中：
+
+```typescript
+tags: [
+  {
+    name: 'Content',
+    description: '内容管理相关接口',
+  },
+  {
+    name: 'Admin',
+    description: '管理员相关接口',
+  },
+],
+```
+
+### 添加服务器配置
+
+```typescript
+servers: [
+  {
+    url: 'http://localhost:3000',
+    description: '开发服务器',
+  },
+  {
+    url: 'https://api.novalon.cn',
+    description: '生产服务器',
+  },
+],
+```
+
+## CI/CD集成
+
+### 验证OpenAPI规范
+
+```bash
+# 安装验证工具
+npm install -g @redocly/cli
+
+# 验证规范
+redocly lint http://localhost:3000/api/docs
+```
+
+### 生成文档
+
+```bash
+# 安装Redoc
+npm install -g redoc
+
+# 生成静态HTML文档
+redocly build-docs http://localhost:3000/api/docs -o api-docs.html
+```
+
+### GitHub Actions示例
+
+```yaml
+name: API Documentation
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Start server
+        run: npm run dev &
+        env:
+          CI: true
+      
+      - name: Wait for server
+        run: npx wait-on http://localhost:3000/api/docs
+      
+      - name: Validate OpenAPI spec
+        run: npx @redocly/cli lint http://localhost:3000/api/docs
+```
+
+## 故障排查
+
+### 问题1：文档页面无法加载
+
+**症状**：访问`/api-docs`显示加载中或空白页
+
+**解决方案**：
+```bash
+# 检查API端点是否正常
+curl http://localhost:3000/api/docs
+
+# 检查浏览器控制台错误
+# 打开开发者工具查看Network和Console标签
+```
+
+### 问题2：API不显示在文档中
+
+**症状**：某些API端点未出现在文档中
+
+**解决方案**：
+```typescript
+// 检查JSDoc注释格式
+// 确保使用 @openapi 标签
+/**
+ * @openapi  // ← 必须是这个标签
+ * /api/your-endpoint:
+ *   get:
+ */
+
+// 检查apis路径配置
+apis: [
+  './src/app/api/**/route.ts',  // ← 确保路径正确
+],
+```
+
+### 问题3：认证失败
+
+**症状**：使用Authorize按钮后仍然无法访问需要认证的API
+
+**解决方案**：
+```bash
+# 确保令牌格式正确
+Bearer your-access-token  # ← 注意Bearer前缀
+
+# 检查令牌是否有效
+curl -H "Authorization: Bearer your-token" http://localhost:3000/api/admin/content
+```
+
+## 参考资源
+
+- [OpenAPI规范](https://swagger.io/specification/)
+- [Swagger UI文档](https://swagger.io/tools/swagger-ui/)
+- [swagger-jsdoc文档](https://github.com/surnet/swagger-jsdoc)
+- [OpenAPI Generator](https://openapi-generator.tech/)
+- [Redoc文档](https://redocly.com/docs/redoc/)
+
+## 总结
+
+OpenAPI文档已完全集成到项目中，提供了：
+
+✅ **交互式API文档**
+✅ **自动生成规范**
+✅ **在线测试功能**
+✅ **认证支持**
+✅ **多格式导出**
+
+通过合理使用OpenAPI文档，可以：
+- 提升API可用性
+- 减少沟通成本
+- 自动化API测试
+- 生成客户端SDK