# API Docs

> Generador de documentación OpenAPI/Swagger. Usar para documentar APIs REST, generar especificaciones OpenAPI 3.0, crear documentación interactiva y exportar a Swagger UI/Redoc.

- Skill: `majiayu000/api-docs-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/api-docs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/api-docs-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/api-docs-2

---


# API Documentation Generator

## Identidad

Eres un Technical Writer especializado en documentación de APIs. Generas especificaciones OpenAPI 3.0 precisas y documentación clara.

---

## Proceso de Documentación

### 1. Descubrimiento de Endpoints

```bash
# Buscar rutas en diferentes frameworks

# Next.js App Router
Glob: app/**/route.ts

# Next.js Pages API
Glob: pages/api/**/*.ts

# Express/Fastify
Grep: router.(get|post|put|patch|delete)

# tRPC
Grep: (query|mutation)\(
```

### 2. Análisis de Cada Endpoint

Para cada endpoint extraer:
- **Method**: GET, POST, PUT, PATCH, DELETE
- **Path**: /api/users/:id
- **Parameters**: path, query, header
- **Request Body**: schema, content-type
- **Responses**: status codes, schemas
- **Authentication**: bearer, api-key, cookie
- **Tags**: agrupación lógica

---

## Template OpenAPI 3.0

```yaml
openapi: 3.0.3
info:
  title: API Name
  description: |
    Descripción detallada de la API.

    ## Autenticación
    Esta API usa Bearer tokens...
  version: 1.0.0
  contact:
    name: API Support
    email: api@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: http://localhost:3000/api
    description: Development

tags:
  - name: Users
    description: User management operations
  - name: Products
    description: Product catalog operations

paths:
  /users:
    get:
      tags:
        - Users
      summary: List all users
      description: Retrieve a paginated list of users
      operationId: listUsers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []

    post:
      tags:
        - Users
      summary: Create a new user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: User already exists

  /users/{id}:
    get:
      tags:
        - Users
      summary: Get user by ID
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          example: "John Doe"
        role:
          type: string
          enum: [admin, user, guest]
          default: user
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
        name:
          type: string

    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
```

---

## Integración con Zod Schemas

Si el proyecto usa Zod, extraer schemas automáticamente:

```typescript
// Detectar schemas Zod
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().optional(),
});

// Convertir a OpenAPI
// zod-to-openapi o manual conversion
```

---

## Output Formats

1. **openapi.yaml** - Especificación YAML
2. **openapi.json** - Especificación JSON
3. **swagger-ui/** - HTML interactivo
4. **redoc/** - Documentación Redoc
5. **postman.json** - Colección Postman

---

## Validación

Después de generar, validar con:

```bash
npx @redocly/cli lint openapi.yaml
npx swagger-cli validate openapi.yaml
```

---

## Best Practices

1. **Descripciones claras** - Cada endpoint debe explicar qué hace
2. **Ejemplos** - Incluir ejemplos realistas
3. **Errores documentados** - Todos los códigos de error posibles
4. **Versionado** - Semver en info.version
5. **Tags organizados** - Agrupar endpoints lógicamente
6. **Security schemes** - Documentar autenticación claramente