Publicación de Documentación de API con Postman

Curso de Introducción al Despliegue de Aplicaciones

Clase 15 de 17

Clase 15 / 17

Recursos

¿Cómo se documenta una API usando Postman?

En un mundo donde las aplicaciones y servicios digitales se disparan cada día, documentar tu API es una estrategia clave para asegurar la comprensión y usabilidad de tus desarrollos por parte de otros desarrolladores y usuarios. A través de Postman, puedes no solo crear y probar tus APIs, sino también generar su documentación y publicarla en Internet, facilitando accesos y entendimiento a quien lo necesite. ¡Vamos a descubrir cómo hacerlo!

¿Cómo guardar las peticiones en una colección?

Antes de poder documentar tu API, debes asegurarte de tener todas las peticiones organizadas. En Postman, esto se puede lograr usando 'colecciones'. Las colecciones actúan como carpetas que te permiten agrupar todas las peticiones relacionadas con tu API. Aquí te explico cómo hacerlo:

Guardar las peticiones: Ve a tu aplicación de Postman y localiza las peticiones realizadas previamente. Utiliza los atajos Ctrl + S o Cmd + S para guardar cada petición.
Nombrar la petición: Puedes asignar un nombre significativo para identificar fácilmente cada petición. Ejemplo: list user, add user, delete user by ID.
Crear la colección: Guarda cada petición en una colección que represente tu proyecto. Nombrarla ayuda a identificarla entre los múltiples proyectos que puedes gestionar en Postman. Ejemplo: curso despliegue apps.

¿Cómo publicar la documentación?

Una vez agrupadas tus peticiones, el siguiente paso es publicar la documentación en línea para permitir acceso público. Esto puede hacerse fácilmente desde la interfaz de Postman:

Seleccionar la colección: Navega hacia la colección recién creada y selecciona los tres puntos que aparecen al lado.
Publicar documentos: Selecciona la opción publicar documentos que aparece en el menú desplegable.
Configurar la publicación: Se abrirá en tu navegador una página de Postman donde podrás configurar opciones de color y sintaxis para la publicación. Puedes dejar las configuraciones por defecto si lo prefieres y hacer clic en publicar colección.
Visitar la URL generada: Postman proporcionará una URL donde la documentación estará disponible en línea. Este enlace se puede compartir con usuarios y desarrolladores para que accedan a la información detallada de tu API.

¿Qué incluye la documentación publicada?

La documentación generada por Postman es extensa y amigable para desarrolladores. Los aspectos destacados incluyen:

Detalles de cada petición: Como los nombres de los verbos HTTP utilizados, el tipo de contenido esperado y ejemplos de peticiones.
Compatibilidad con múltiples lenguajes: Postman muestra cómo se implementan las peticiones en diferentes lenguajes de programación como Java, NodeJS, entre otros, lo que amplía las posibilidades de uso para distintos tipos de desarrolladores.

Con estos pasos, has aprendido no solo a estructurar y gestionar mejor tus API, sino también a compartirlas eficientemente con el mundo, facilitando su adopción. Afianza tus conocimientos y sigue explorando las posibilidades que Postman te ofrece para optimizar tus proyectos de desarrollo. ¡Está a un clic de distancia!