api-docs-writer

Skill API Docs Writer

Este skill transforma especificaciones de API brutas, descripciones de endpoints o colecciones de Postman en documentación limpia orientada a desarrolladores, siguiendo convenciones similares a OpenAPI. El resultado está listo para un portal de desarrolladores, README o página de Notion/Confluence.

Entradas Requeridas

Solicita al usuario estos datos si no están disponibles:

• Detalles de API o endpoint (especificación bruta, exportación de Postman o descripción verbal)
• Método de autenticación (clave de API / token Bearer / OAuth 2.0 / Ninguno)
• URL base
• Versión de API (p. ej. v1, v2.3, o "sin versión" — afecta notas de deprecación y headers de versionado)
• Límites de velocidad (solicitudes por segundo/minuto por token o IP, si se conocen — o "desconocido")
• Audiencia (desarrolladores internos / partners externos / público)
• Formato de salida (Markdown para portales de desarrolladores y READMEs / Prosa simple para Confluence o Notion — nota: este skill no produce YAML de OpenAPI)

Formato de Salida

Para cada endpoint, produce lo siguiente:

---

[MÉTODO] /ruta/al/endpoint

Resumen: [Una línea — qué hace este endpoint]

Descripción: [2–4 oraciones. Cuándo usar este endpoint. Qué devuelve. Comportamiento importante a conocer (paginación, límites de velocidad, procesamiento asíncrono, etc.)]

Autenticación: [Requerida / Opcional — método]

---

Solicitud

Headers:

| Header | Requerido | Descripción |

|---|---|---|

| Authorization | Sí | Bearer <token> |

| Content-Type | Sí | application/json |

Parámetros de Ruta:

| Parámetro | Tipo | Requerido | Descripción |

|---|---|---|---|

| id | string | Sí | Identificador único del recurso |

Parámetros de Consulta:

| Parámetro | Tipo | Requerido | Predeterminado | Descripción |

|---|---|---|---|---|

| limit | integer | No | 20 | Máximo de resultados por página (1–100) |

| cursor | string | No | — | Cursor de paginación de respuesta anterior |

Cuerpo de la Solicitud:

{
  "field_name": "value",
  "another_field": 42
}

| Campo | Tipo | Requerido | Descripción |

|---|---|---|---|

| field_name | string | Sí | [Descripción clara de qué hace este campo] |

| another_field | integer | No | [Descripción. Incluye rango válido o valores enum si aplica] |

---

Respuesta

Respuesta de Éxito: 200 OK

{
  "id": "abc123",
  "status": "active",
  "created_at": "2025-04-01T10:00:00Z"
}

| Campo | Tipo | Descripción |

|---|---|---|

| id | string | Identificador único del recurso creado/recuperado |

| status | string | Estado actual. Enum: active, inactive, pending |

| created_at | string ISO 8601 | Timestamp de creación en UTC |

---

Códigos de Error

| Código de Estado | Código de Error | Descripción | Cómo Resolver |

|---|---|---|---|

| 400 | INVALID_REQUEST | El cuerpo de solicitud está malformado o falta campos requeridos | Verifica el cuerpo de solicitud contra el schema anterior |

| 401 | UNAUTHORIZED | Token de autenticación faltante o inválido | Verifica tu clave de API o refresca tu token |

| 404 | NOT_FOUND | El recurso solicitado no existe | Verifica el ID en el parámetro de ruta |

| 429 | RATE_LIMITED | Demasiadas solicitudes | Retrocede e intenta de nuevo después del valor del header Retry-After |

| 500 | INTERNAL_ERROR | Error inesperado del servidor | Reinténtalo con backoff exponencial; contacta soporte si persiste |

---

Ejemplos de Código

Produce ejemplos en al menos 2 lenguajes relevantes para la audiencia (predeterminado: cURL + Python):

cURL:

curl -X POST https://api.example.com/v1/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "value"}'

Python:

import requests

response = requests.post(
    "https://api.example.com/v1/endpoint",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"field_name": "value"}
)
data = response.json()

---

Controles de Calidad

• [ ] Cada parámetro está documentado (tipo, requerido/opcional, descripción)
• [ ] Los campos de respuesta están completamente documentados con tipos
• [ ] Se listan todos los códigos de error relevantes con orientación de resolución
• [ ] Los códigos de error cubren como mínimo: 400 (solicitud incorrecta), 401/403 (autenticación), 404 (no encontrado), 429 (límite de velocidad), 500 (error del servidor) — o indica explícitamente cuáles no aplican a este endpoint
• [ ] Los ejemplos de código usan la URL base actual y un token placeholder realista — ningún ejemplo referencia variables indefinidas o "YOUR_ENDPOINT" fuera del snippet
• [ ] El método de autenticación se indica claramente arriba
• [ ] Los valores enum se listan donde aplica
• [ ] Se documenta la paginación si el endpoint es un endpoint de lista

Anti-Patrones

• [ ] No documentes solo el camino feliz — cada endpoint debe tener códigos de error para al menos 400, 401/403, 404, 429 y 500
• [ ] No uses valores placeholder como "YOUR_ENDPOINT" o "INSERT_TOKEN" en ejemplos de código — usa placeholders realistas anclados a la URL base actual
• [ ] No omitas valores enum para campos con un conjunto fijo de valores aceptados — los enums no documentados causan bugs de integración
• [ ] No omitas documentación de paginación en endpoints de lista — los desarrolladores que se la pierdan construirán integraciones que silenciosamente pierdan datos
• [ ] No describa qué es un campo sin describir qué hace — "el ID" no es documentación; "el identificador único usado para recuperar o actualizar este recurso" lo es

Ejemplos de Uso

• "Documenta este endpoint de API: [pega especificación o descripción]"
• "Convierte esta colección de Postman en documentos para desarrolladores"
• "Escribe documentación de referencia de API para [endpoint]"
• "Escribe una guía para desarrolladores para nuestra API de [producto]"