mcpField
A
api-reference-documentation

api-reference-documentation

github.com/aj-geddes开发373496 次安装34 周前更新
代码仓库

关于 api-reference-documentation

面向开发者的 API 参考文档编写技能，涵盖端点、认证、请求与响应示例及交互式文档，并提供 REST、GraphQL、OpenAPI 和 SDK 等主题的指导。

主要功能

  1. 01OpenAPI 规范指导
  2. 02端点与参数文档
  3. 03认证和错误示例
  4. 04SDK 与客户端库文档
  5. 05Webhook 与版本指南

适用场景

  1. 01编写 REST API 文档
  2. 02撰写 GraphQL API 参考
  3. 03准备认证和速率限制指南
  4. 04记录 Webhook 与 API 版本

安装

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

$npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill api-reference-documentation

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
list-products.md
openapi-specification-example.md
scripts/
validate-api.sh
templates/
api-scaffold.yaml

详细介绍

API 参考文档

目录

概述

生成专业的 API 文档，帮助开发者集成你的 API，内容包括端点规范、身份验证、请求/响应示例和交互式文档。

适用场景

  • 编写 REST API 文档
  • 创建 OpenAPI/Swagger 规范
  • 编写 GraphQL API 文档
  • 编写 SDK 和客户端库文档
  • 编写 API 身份验证指南
  • 编写速率限制文档
  • 编写 Webhook 文档
  • 编写 API 版本管理指南

快速入门

最简可运行示例：

openapi: 3.0.3
info:
  title: E-Commerce API
  description: |
    Complete API for managing e-commerce operations including products,
    orders, customers, and payments.

    ## Authentication
    All endpoints require Bearer token authentication. Include your API key
    in the Authorization header: `Authorization: Bearer YOUR_API_KEY`

    ## Rate Limiting
    - 1000 requests per hour for authenticated users
    - 100 requests per hour for unauthenticated requests

    ## Pagination
    List endpoints return paginated results with `page` and `limit` parameters.
  version: 2.0.0
  contact:
    name: API Support
    email: [email protected]
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南内容
OpenAPI 规范示例openapi: 3.0.3
列出产品列出产品

最佳实践

✅ 应该
  • 使用 OpenAPI 3.0+ 规范
  • 为每个端点提供请求/响应示例
  • 记录所有查询参数和标头
  • 提供身份验证示例
  • 包含错误响应格式
  • 记录速率限制和分页信息
  • 使用一致的命名约定
  • 提供多种语言的 SDK 示例
  • 记录 Webhook 负载
  • 提供交互式 API 浏览器（Swagger UI）
  • 为 API 文档进行版本管理
  • 为不兼容变更提供迁移指南
❌ 不应该
  • 跳过错误响应文档
  • 忘记记录身份验证
  • 使用不一致的术语
  • 不记录端点
  • 忽略弃用通知
  • 跳过版本信息

评论

支持 Markdown