Documentación Interactiva de APIs con Markdown y Ejemplos
Aprende a transformar cualquier colección de Postman en un portal web de documentación interactivo con soporte completo de Markdown, ejemplos guardados y snippets de código.
La Documentación como Contrato de Software
Una API sin documentación clara es prácticamente inutilizable. En lugar de obligar al equipo de Frontend, a los clientes o a terceros a adivinar qué cabeceras o formatos JSON requiere un endpoint, Postman permite autogenerar portales de documentación web completos directamente desde tus colecciones.
Enriquecimiento con Markdown en Cada Nivel
En Postman, puedes añadir descripciones redactadas en Markdown enriquecido en cuatro niveles jerárquicos:
- A nivel de Colección: Introducción general de la API, políticas de seguridad, cómo obtener la API Key y rate limits.
- A nivel de Carpeta: Descripción del módulo de negocio (ej. Módulo de Facturación o Catálogo de Productos).
- A nivel de Petición: Explicación de la acción, permisos requeridos y tabla de parámetros.
- A nivel de Parámetro: Cada Query Param o campo en el Body cuenta con su propia casilla de descripción.
Guardar Respuestas de Ejemplo (Save as Example)
Una de las mejores prácticas consiste en registrar ejemplos reales de cómo responde el servidor en diferentes situaciones:
- Envía la petición con datos válidos para recibir un
200 OK. - En la esquina superior derecha del panel de respuesta, haz clic en Save as Example.
- Renombra el ejemplo como "200 OK - Usuario Creado Exitosamente".
- Repite enviando datos erróneos para capturar y guardar un ejemplo "422 Unprocessable Entity - Email Duplicado".
⚡ Estructura Markdown Recomendada para Documentar un Endpoint en Postman
Plantilla en Markdown para pegar en el panel "Documentation" de una petición:
# Crear Nuevo Usuario
Registra un nuevo usuario en la plataforma Kilopolis y envía el correo de activación.
### Requisitos de Autorización
- **Tipo de Auth:** Bearer Token (JWT).
- **Rol requerido:** `admin` o `superadmin`.
### Parámetros del Body (application/json)
| Campo | Tipo | Requerido | Descripción |
| :--- | :--- | :--- | :--- |
| `nombre` | `string` | **Sí** | Nombre completo (mínimo 3 caracteres). |
| `email` | `string` | **Sí** | Correo electrónico único válido. |
| `rol` | `string` | No | Opciones: `estudiante`, `editor`, `admin`. Por defecto: `estudiante`. |
### Respuestas Posibles
- **201 Created:** Usuario creado satisfactoriamente en base de datos.
- **400 Bad Request:** Formato JSON malformado.
- **409 Conflict:** Ya existe una cuenta asociada a ese correo electrónico.
- **401 Unauthorized:** Token no provisto o expirado.Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Qué función de Postman permite mostrar a los consumidores de una API cómo luce una respuesta exitosa (200) o un error (404) sin necesidad de conectarse al servidor en vivo?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar Manual de Postman: Pruebas de APIs REST & Automatización y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.
🏛️ Autoría y Propiedad Intelectual: Obra educativa original de David Amador para Kilopolis Academia (Solucionáticos), estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.