Lección 12 de 12 · Lectura y práctica
Documentación con Swagger y despliegue en producción
Lección práctica para aplicar Documentación con Swagger y despliegue en producción dentro de Construcción de APIs RESTful con Node.js y Express, con criterios de decisión, ejemplo guiado, ejercicio y checklist de salida.
Del concepto a la práctica
Taller de esta lección
La documentación es un contrato operativo: debe permitir reproducir una llamada sin adivinar nombres, tipos ni respuestas. Para un servicio de reservas, documenta POST /reservas con cuerpo, autenticación requerida, respuesta 201, error 400 y conflicto 409. El despliegue debe leer configuración del entorno y tener una comprobación de salud separada.
Ejemplo resuelto
Una especificación puede describir POST /reservas, clienteId como entero y fecha como cadena de fecha. El ejemplo { "clienteId": 8, "fecha":"2026-10-12" } debe coincidir con la validación real. GET /salud puede responder 200 con { "estado":"ok" }; el proceso usa PORT del entorno y no incluye secretos en el documento. Esa salud básica solo confirma que el proceso responde; define una comprobación de disponibilidad separada si necesitas saber que la base de datos acepta consultas.
Pruébalo
Escribe una entrada para ruta, parámetros, cuerpo y respuestas.
Compara cada ejemplo con el controlador y el validador.
Configura
PORTsin fijarlo en código de producción.Ejecuta la comprobación de salud y registra su código.
Error frecuente: documentar una respuesta ideal que el servidor no produce. Corrígelo probando el ejemplo y ajustando documento o implementación, nunca ocultando la discrepancia.
Comprueba tu resultado
La llamada documentada reproduce 201 con los mismos nombres de campo. Un clienteId ausente produce 400; una reserva duplicada produce 409. La salud responde 200 y el arranque cambia de puerto al cambiar PORT.
Mapa de prácticaEl navegador envía una solicitud a la API. El servidor valida la operación y consulta los datos; después devuelve una respuesta que el navegador puede mostrar. La base de datos se comunica con el servidor y no directamente con el navegador.
Ver la infografía en tamaño completo ↗Sigue con Construcción de APIs RESTful con Node.js y Express
Esta lección forma parte de un curso de Cursalo. Revisa su programa y elige entre la compra individual o el acceso a toda la escuela.
Si ya tenías acceso a este curso, entra con tu cuenta: tus derechos y tu progreso se conservan. No necesitas comprarlo de nuevo.