mcpField
A
api-docs

api-docs

github.com/langchain-ai开发11960 次安装11 周前更新
代码仓库

关于 api-docs

api-docs 是用于设计和编写 RESTful API 文档的技能，面向 API 开发者。它强调 OpenAPI 3.0+、REST 约定及结构化错误响应。

主要功能

  1. 01遵循 OpenAPI 3.0+
  2. 02使用 REST 资源命名约定
  3. 03规范 HTTP 方法与状态码
  4. 04支持列表分页与 API 版本
  5. 05定义结构化错误响应

适用场景

  1. 01为 REST API 编写接口规范
  2. 02统一团队的 HTTP 方法和状态码
  3. 03为列表端点设计分页参数

安装

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

$npx skills add https://github.com/langchain-ai/skills-benchmarks --skill api-docs

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

详细介绍

API 文档规范

遵循行业标准设计和编写 RESTful API 文档。

OpenAPI 规范

始终使用 OpenAPI 3.0+ 编写 API 文档：

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email

REST 约定

  1. 使用名词表示资源：/users、/orders
  2. 正确使用 HTTP 方法：GET、POST、PUT、PATCH、DELETE
  3. 返回适当的状态码：200、201、400、404、500
  4. 为列表使用分页：?page=1&limit=20
  5. 为 API 添加版本号：/v1/users

错误响应

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}

评论

支持 Markdown