Este artículo también está disponible en: English (Inglés)
Después de que tú o tu organización hayáis pasado meses desarrollando vuestros servicios, llega el momento en el que tienes que documentar tu API.
En lugar de escribir la documentación a mano y tardar semanas en hacer una documentación legible, disponemos de multitud de herramientas que nos simplifican esta tarea.
Voy a explicar cómo generar la documentación técnica de tu API en menos de 15 minutos.
Hay varias maneras de documentar una API. Merece una mención honorífica Swagger. Swagger es una serie de herramientas OpenSource que permiten crear la documentación de tu API a partir de comentarios en tu código o de un modelo definido. Recomiendo más esta herramienta si aún no has creado tu servicio y estás creando el modelo. Pero en nuestro caso, ya tenemos el servicio y para eso Postman es mejor.
Crear la documentación con Postman nos permitirá tener un enlace público o privado a la documentación de la API de nuestro servicio y proporcionará un control de versiones de los cambios, modificar la documentación colaborativamente y mucho más. Todo esto gratis y agnóstico del lenguaje en el que hayas desarrollado.
Empezando
Para crear nuestra documentación con Postman, por supuesto, necesitaremos Postman. Así que si no lo tienes: descárgatelo.
¿Qué es Postman?
Es un cliente para hacer llamadas REST, SOAP y GraphQL. Con funciones como pruebas automáticas de tus servicios, monitorizar el estado de tu API, trabajar colaborativamente en el desarrollo del mockup de tu API y mucho más.
Aprende más sobre Postman aquí: Guía inicial Postman.
El proceso para crear la documentación es sencillo. Básicamente, tenemos que tener la colección de llamadas a la API que queramos recoger en la documentación. Y añadir las descripciones pertinentes a cada llamada y parámetro.
¡Así que vamos allá!
Aviso: Si tienes ya una colección con tus llamadas puedes saltarte estos pasos e ir directamente al apartado de Documentar.
Crear una colección en Postman
Una colección es una carpeta que guarda el conjunto de solicitudes relacionadas con una misma API.
Para crear la nueva colección pulsamos en “New Collection” en la columna izquierda del panel de Postman. Añadimos el nombre y una descripción de la API. Estos datos se añadirán a la documentación de tu API.
Añadir una llamada
Una vez creada nuestra colección, tenemos que añadir las distintas llamadas que queremos incluir en la documentación de la API. Lo bueno de Postman, es que al ser un cliente para pruebas API Rest, podemos usarlo para probar que nuestras llamadas funcionan, antes de ser añadidas a la documentación.
Para añadir una nueva llamada en nuestra colección recién creada, pulsamos en “Add request” o hacemos una nueva pestaña en la vista de solicitudes.
Aquí nos toca añadir los datos de la llamada a nuestra API y tocará hacer esto para cada una de las llamadas de la API que queramos incluir en la documentación.
Probaremos nuestra solicitud y podremos guardar la respuesta como un ejemplo de respuesta que se presentará en la documentación. Con una llamada exitosa, también garantizaremos que los Headers y los verbos HTTP (GET, POST, PUT, …) funcionen y se añadan correctamente a la documentación.
Documentar
Para darle más estructura a la documentación, podemos crear carpetas dentro de las colecciones, para así, organizar mejor las llamadas por categorías.
También es conveniente, que añadas descripciones a las llamadas y a los parámetros, para que tu documentación esté completa.
Esto lo puedes añadir a la hora de guardar la llamada en la colección, acuérdate de seleccionar la colección que acabas de crear.
Con esto ya tenemos una Colección que contiene llamadas a nuestra API y si las hemos probado, ya tenemos también las respuestas de ejemplo. Si hemos añadido las descripciones a nuestros parámetros y a nuestras Requests, tendríamos ya toda la información lista para hacer la documentación. – Y así es, ya está a pocos clics de distancia el resultado final.
Generando documentación
Para generar la documentación y poder sembrar los maravillosos frutos de nuestro trabajo, sólo tenemos que ir a las opciones de la colección y pulsar “Publish Docs”.
Se te abrirá una ventana en el navegador, donde te permitirá configurar los detalles de tu documentación. No hace falta modificar nada para que funcione, pero se puede adaptar a las necesidades que tengas. Para finalizar, pulsas el gran botón de “Publish” en esa ventana del navegador y ya tendrás el enlace público a tu documentación creada.
Más cositas
Ahora ya tenemos la documentación de nuestra API. Conforme actualicemos nuestras llamadas en Postman y las guardemos, podemos volver a publicar para actualizar los cambios.
También podéis invitar a editores, para que puedan descargarse la colección de llamadas, probarlas y modificarlas.
Con esto ya tenemos documentación de nuestra API.
¡Gratis, alojada, clara y en menos de 15 minutos!