API 文档

API 文档工作流

概述

专门用于创建全面 API 文档的工作流，包括 OpenAPI/Swagger 规范、开发者指南、代码示例和交互式文档。

何时使用此工作流

在以下场景中使用此工作流：

• 创建 API 文档

• 生成 OpenAPI 规范

• 编写开发者指南

• 添加代码示例

• 搭建 API 门户

工作流阶段

阶段 1：API 探索

#### 调用的技能

• api-documenter - API 文档

• api-design-principles - API 设计

#### 执行动作
1. 盘点端点 (Endpoints)
2. 记录请求/响应
3. 确定身份验证方式
4. 映射错误代码
5. 记录速率限制

#### 可复制提示词

Use @api-documenter to discover and document API endpoints

阶段 2：OpenAPI 规范

#### 调用的技能

• openapi-spec-generation - OpenAPI

• api-documenter - API 规范

#### 执行动作
1. 创建 OpenAPI 架构 (Schema)
2. 定义路径 (Paths)
3. 添加架构
4. 配置安全性
5. 添加示例

#### 可复制提示词

Use @openapi-spec-generation to create OpenAPI specification

阶段 3：开发者指南

#### 调用的技能

• api-documentation-generator - 文档

• documentation-templates - 模板

#### 执行动作
1. 创建快速入门指南
2. 编写身份验证指南
3. 记录常用模式
4. 添加故障排除
5. 创建 FAQ

#### 可复制提示词

Use @api-documentation-generator to create developer guide

阶段 4：代码示例

#### 调用的技能

• api-documenter - 代码示例

• tutorial-engineer - 教程

#### 执行动作
1. 创建请求示例
2. 编写 SDK 示例
3. 添加 curl 示例
4. 创建教程
5. 测试示例

#### 可复制提示词

Use @api-documenter to generate code examples

阶段 5：交互式文档

#### 调用的技能

• api-documenter - 交互式文档

#### 执行动作
1. 搭建 Swagger UI
2. 配置 Redoc
3. 添加“试用 (Try-it)”功能
4. 测试交互性
5. 部署文档

#### 可复制提示词

Use @api-documenter to set up interactive documentation

阶段 6：文档站点

#### 调用的技能

• docs-architect - 文档架构

• wiki-page-writer - 文档

#### 执行动作
1. 选择平台
2. 设计结构
3. 创建页面
4. 添加导航
5. 配置搜索

#### 可复制提示词

Use @docs-architect to design API documentation site

阶段 7：维护

#### 调用的技能

• api-documenter - 文档维护

#### 执行动作
1. 设置自动生成
2. 配置验证
3. 添加审核流程
4. 计划更新
5. 监控反馈

#### 可复制提示词

Use @api-documenter to set up automated doc generation

质量关卡

• [ ] OpenAPI 规范完整

• [ ] 开发者指南已完成

• [ ] 代码示例可运行

• [ ] 交互式文档功能正常

• [ ] 文档已部署

相关工作流包

• documentation - 文档

• api-development - API 开发

• development - 开发

局限性

• 仅在任务明确符合上述范围时使用此技能。

• 不要将输出结果视为特定环境验证、测试或专家评审的替代方案。

• 停止并询问...