mcpField
A
api-documenter

api-documenter

github.com/404kidwiz开发99 次安装
代码仓库

关于 api-documenter

API Documenter 是面向开发者的技能，用于编写准确易读的 API 文档，涵盖 OpenAPI 规范、GraphQL Schema、交互式参考文档和入门指南。

主要功能

  1. 01编写 OpenAPI 规范
  2. 02编制 REST 端点参考文档
  3. 03编写 GraphQL Schema 文档
  4. 04规划交互式 API 参考
  5. 05撰写 API 入门指南

适用场景

  1. 01记录 REST API 及其错误
  2. 02编写 GraphQL Schema 指南
  3. 03制作 API 身份验证教程
  4. 04准备 SDK 使用示例

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/404kidwiz/claude-supercode-skills --skill api-documenter

安装后在 Claude Code 中输入/api-documenter确认已加载。

详细介绍

API 文档编写器

用途

擅长创建清晰、准确且便于开发者使用的 API 文档。专注于 OpenAPI 3.x 规范、GraphQL 架构文档和交互式 API 参考。

适用场景

  • 编写 OpenAPI/Swagger 规范
  • 编写 REST API 端点文档
  • 创建 GraphQL 架构文档
  • 构建交互式 API 参考
  • 编写 API 入门指南
  • 编写身份验证流程文档
  • 创建 SDK 使用示例

快速入门

在以下场景中调用此技能：

  • 编写 OpenAPI/Swagger 规范
  • 编写 REST API 端点文档
  • 创建 GraphQL 架构文档
  • 构建交互式 API 参考
  • 编写 SDK 使用示例

在以下场景中不要调用：

  • 设计 API 架构（使用 api-designer）
  • 编写面向用户的产品文档（使用 technical-writer）
  • 创建内部系统文档（使用 document-writer）
  • 构建实际的 API（使用后端开发技能）

决策框架

Documentation Type:
├── New API → OpenAPI spec first, then guides
├── Existing API → Audit endpoints, generate spec
├── GraphQL → Schema docs + query examples
├── SDK/Library → Code samples + quickstart
└── Microservices → Service catalog + contracts

核心工作流

1. 创建 OpenAPI 规范
  1. 梳理所有端点和方法
  2. 定义请求和响应架构
  3. 编写参数和标头文档
  4. 添加身份验证要求
  5. 添加请求和响应示例
  6. 使用 lint 工具验证规范
2. API 参考文档
  1. 按资源或领域对端点分组
  2. 撰写清晰的端点说明
  3. 为所有参数注明类型
  4. 提供请求和响应示例
  5. 包含错误代码和处理方式
  6. 添加身份验证示例
3. API 入门指南
  1. 说明身份验证设置
  2. 展示第一个 API 调用示例
  3. 介绍常见用例
  4. 包含 SDK 安装步骤
  5. 提供故障排查建议
  6. 链接到完整参考文档

最佳实践

  • 在所有文档中使用一致的术语
  • 提供可直接复制粘贴的代码示例
  • 同时包含成功和错误响应
  • 按 API 版本为文档标注版本
  • 发布前测试所有代码示例
  • 添加速率限制和配额信息

反模式

反模式问题正确做法
没有示例开发者只能猜测用法包含请求和响应示例
文档过时损害开发者的信任自动根据代码生成文档
缺少错误信息在生产环境中导致意外故障记录所有错误代码
行话过多让新开发者感到困惑使用清晰、简单的语言
没有版本管理无法明确了解重大变更根据 API 版本管理文档

评论

支持 Markdown