mcpField
A
api-docs

api-docs

github.com/langchain-aiDevelopment11960 installsUpdated 11w ago
Repository

About api-docs

api-docs is a skill for developers designing and documenting RESTful APIs. It focuses on OpenAPI 3.0+, REST conventions, and structured error responses.

Key features

  1. 01Follow OpenAPI 3.0+
  2. 02Apply REST resource naming
  3. 03Specify HTTP methods and status codes
  4. 04Add pagination and API versions
  5. 05Define structured error responses

Use cases

  1. 01Document a REST API
  2. 02Standardize methods and status codes
  3. 03Design pagination for list endpoints

Install

Copy the command and run it in a terminal.

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

After installing, type/api-docsin Claude Code to confirm it loaded.

Details

From the project README

API Documentation Standards

Design and document RESTful APIs following industry standards.

OpenAPI Specification

Always document APIs using OpenAPI 3.0+:

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 Conventions

  1. Use nouns for resources: /users, /orders
  2. Use HTTP methods correctly: GET, POST, PUT, PATCH, DELETE
  3. Return appropriate status codes: 200, 201, 400, 404, 500
  4. Use pagination for lists: ?page=1&limit=20
  5. Version your API: /v1/users

Error Responses

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

Comments

Markdown supported