> ## Content Index
> Fetch the complete content index at: https://www.digitalbrain.news/llms.txt
> Use this file to discover other available public pages before exploring further.

# Prompt para documentar una API REST de forma clara
- URL: https://www.digitalbrain.news/prompts/prompt-documentar-api-rest-clara/
- Published: 2026-06-09T11:45:00.000Z
- Updated: 2026-09-03T09:05:28.000Z
- Description: Cuando lanzas una API o necesitas documentar endpoints existentes. Te genera docs de calidad Stripe que puedes publicar directamente.
- Author: Ramón Pérez Coronado
- Tags: #prompts, api, documentacion, desarrollo

Cuando lanzas una API o necesitas documentar endpoints existentes. Te genera docs de calidad Stripe que puedes publicar directamente.

## El prompt

```

Eres un technical writer que ha documentado APIs para empresas como Stripe, Twilio y Notion. Tu documentación se caracteriza por ser usable: un developer puede integrarse leyendo solo los docs, sin preguntar a nadie.

Documenta la siguiente API con esta estructura para cada endpoint:

1. DESCRIPCIÓN: 1-2 líneas de qué hace este endpoint.
2. MÉTODO + URL: GET /api/v1/resource
3. HEADERS: Los que son obligatorios (auth, content-type).
4. PARÁMETROS:
   - Path params: nombre, tipo, descripción
   - Query params: nombre, tipo, requerido/opcional, default,      descripción
   - Body: JSON schema con tipos y descripción por campo
5. RESPUESTA EXITOSA: Status code + JSON de ejemplo con datos realistas (no 'string', sino 'María García').
6. ERRORES: Los 3-5 errores más comunes con status code, mensaje y cómo resolverlos.
7. EJEMPLO: curl completo listo para copiar y pegar.
8. RATE LIMITS: Si aplica.
9. NOTAS: Gotchas, limitaciones conocidas, comportamientos no obvios.

API a documentar: [pegar endpoints, código del handler, o descripción]

```

## Cómo usarlo

**Modelo recomendado:** [Claude](https://www.digitalbrain.news/guias/que-es-claude-ia/)

### Ejemplo de input

\[Endpoint POST /api/v1/subscribers que crea un suscriptor en la newsletter\]

### Ejemplo de output

## POST /api/v1/subscribers

Crea un nuevo suscriptor en la newsletter.

## Body:

```
{"email": "maria@empresa.com", "name": "María García", "tags": ["founder", "tech"]}
```

## 201 Created:

```
{"id": "sub_abc123", "email": "maria@empresa.com", "status": "active"}
```

## Errores comunes:

- 409: Email ya existe. Solución: usar PUT para actualizar.

## Contexto

Cómo documentar una API con IA al nivel de Stripe

La diferencia entre una API con buena documentación y una con mala documentación es simple: con buena docs, la gente se integra sola. Con mala docs, tu inbox se llena de preguntas que deberían estar resueltas en un README.

Este [prompt](https://www.digitalbrain.news/guias/que-es-un-prompt/) genera documentación al estilo Stripe: cada endpoint tiene descripción, parámetros con tipos, respuesta de ejemplo con datos realistas, errores comunes con solución, y un curl que funciona al copiarlo.

El detalle clave: datos realistas en los ejemplos. Un JSON con 'string' como valor no le dice nada a nadie. Un JSON con 'María García' y 'maria@empresa.com' se entiende al instante.

Funciona dándole el código del handler, los endpoints en formato lista, o una descripción de lo que hace la API. Cuanto más información le des, más completa será la documentación. Si tienes tests de la API, pégalos también: son la mejor fuente de edge cases.

Fuente original: [digitalbrain.email](https://digitalbrain.email/?ref=digitalbrain.news)

---

**Relacionado**

[Qué es un MCP server y cómo funciona](https://www.digitalbrain.news/guias/que-es-un-mcp-server/)[Prompt para crear un CLAUDE.md completo para tu proyecto](https://www.digitalbrain.news/prompts/prompt-crear-claude-md-completo-proyecto/)[![Claude Code estrena navegador propio en el escritorio para leer webs sin abrir Chrome](https://storage.ghost.io/c/6d/e3/6de31f63-d0a8-45df-9c6a-481016520347/content/images/size/w300/2026/07/claude-code-navegador-escritorio.jpg)Claude Code estrena navegador propio en el escritorio para leer webs sin abrir Chrome](https://www.digitalbrain.news/noticias/claude-code-navegador-escritorio/)