api-documentation

API 文档工作流

概述

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

何时使用此工作流

在以下情况下使用此工作流：

• 创建 API 文档
• 生成 OpenAPI 规范
• 编写开发者指南
• 添加代码示例
• 设置 API 门户

范围和执行

选择与用户任务相匹配的阶段；本文档是索引，并非要求运行所有列出的技能的指令。使用技能前，请先阅读所选技能。遵守仓库和用户的约束。云端调用、主机配置、发布、破坏性操作和支出均需获得适用的授权；工作流检查清单本身不构成授权。

以实际实现或规范为依据确定契约，并确保示例中不包含机密信息。“试用”功能可能会发送真实请求：请使用明确指定的沙盒端点和测试凭据。发布前，请在本地预览文档；部署是单独的授权操作。

工作流阶段

阶段 1：API 发现

要调用的技能

• api-documenter - API 文档
• api-design-principles - API 设计

操作

1. 清点端点
2. 记录请求/响应
3. 确认身份验证方式
4. 梳理错误代码
5. 记录速率限制

可复制粘贴的提示词

Use @api-documenter to discover and document API endpoints

阶段 2：OpenAPI 规范

要调用的技能

• openapi-spec-generation - OpenAPI
• api-documenter - API 规范

操作

1. 创建 OpenAPI 架构
2. 定义路径
3. 添加架构
4. 配置安全性
5. 添加示例

可复制粘贴的提示词

Use @openapi-spec-generation to create OpenAPI specification

阶段 3：开发者指南

要调用的技能

• api-documentation-generator - 文档
• documentation-templates - 模板

操作

1. 创建入门指南
2. 编写身份验证指南
3. 记录常见模式
4. 添加故障排除指南
5. 创建常见问题解答

可复制粘贴的提示词

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. 添加试用功能
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-design-principles - API 契约设计
• development - 开发

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为对特定环境验证、测试或专家审查的替代。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。