mcpField
A
api-reference-documentation

api-reference-documentation

github.com/secondsky开发240460 次安装5 周前更新
代码仓库

关于 api-reference-documentation

用于编写 API 参考文档的技能，提供 OpenAPI 规范、端点细节、示例和维护方面的指导，面向为集成编写 API 文档的开发者。

主要功能

  1. 01OpenAPI 3.0 规范指导
  2. 02端点与参数检查清单
  3. 03请求和响应示例
  4. 04认证与错误说明
  5. 05版本及迁移指导
  6. 06交互式探索工具建议

适用场景

  1. 01为开发者集成编写 API 文档
  2. 02检查端点参考信息是否完整
  3. 03说明认证方式和错误响应
  4. 04为不兼容变更准备文档

安装

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

$npx skills add https://github.com/secondsky/claude-skills --skill api-reference-documentation

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

详细介绍

API 参考文档

为开发者集成编写全面的 API 文档。

OpenAPI 3.0 规范

openapi: 3.0.3
info:
  title: E-Commerce API
  version: 1.0.0
  description: API for managing products and orders
  contact:
    email: [email protected]

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

security:
  - bearerAuth: []

paths:
  /products:
    get:
      summary: List products
      tags: [Products]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
        - name: category
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id: { type: string, format: uuid }
        name: { type: string, maxLength: 200 }
        price: { type: number, minimum: 0 }
        description: { type: string }

文档检查清单

  • 为所有端点提供文档和示例
  • 说明身份验证方法
  • 指定错误响应
  • 说明速率限制
  • 说明分页
  • 编写 Webhook 文档（如适用）
  • 提供多种语言的 SDK 示例

最佳实践

  • 使用 OpenAPI 3.0+ 规范
  • 包含请求和响应示例
  • 记录所有参数和标头
  • 提供身份验证示例
  • 启用交互式 API 探索
  • 维护版本文档
  • 为不兼容变更提供迁移指南

工具

  • Swagger Editor / Swagger UI
  • Redoc
  • Postman 文档
  • Stoplight

评论

支持 Markdown