api-docs

$npx mdskill add langchain-ai/skills-benchmarks/api-docs

Generate OpenAPI specs and REST patterns for API design.

  • Creates standardized documentation for RESTful endpoints.
  • Integrates with YAML and JSON schema generation tools.
  • Decides structure based on resource naming and HTTP verbs.
  • Delivers formatted YAML or JSON code blocks directly.

SKILL.md

.github/skills/api-docsView on GitHub ↗
---
name: api-docs
description: OpenAPI documentation and REST API design patterns
---

# API Documentation Standards

Design and document RESTful APIs following industry standards.

## OpenAPI Specification

Always document APIs using OpenAPI 3.0+:

```yaml
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

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

More from langchain-ai/skills-benchmarks

SkillDescription
framework-selection"INVOKE THIS SKILL at the START of any LangChain/LangGraph/Deep Agents project, before writing any agent code. Determines which framework layer is right for the task: LangChain, LangGraph, Deep Agents, or a combination. Must be consulted before other agent skills."
langchain-oss-primer"ALWAYS START HERE for any LangChain, Deep Agents, or LangGraph agent building project. Required starting point before choosing other skills or writing any code. Covers framework selection (LangChain vs LangGraph vs Deep Agents), agent archetypes, dependency setup, and which skills to load next based on your decisions."
langsmith-dataset"INVOKE THIS SKILL when creating evaluation datasets, uploading datasets to LangSmith, or managing existing datasets. Covers dataset types (final_response, single_step, trajectory, RAG), CLI management commands, SDK-based creation, and example management. Uses the langsmith CLI tool."
langsmith-evaluatorINVOKE THIS SKILL when building evaluation pipelines for LangSmith. Covers three core components: (1) Creating Evaluators - LLM-as-Judge, custom code; (2) Defining Run Functions - how to capture outputs and trajectories from your agent; (3) Running Evaluations - locally with evaluate() or auto-run via LangSmith. Uses the langsmith CLI tool.
react-componentsModern React component patterns with hooks and TypeScript