Hola gente del futuro.
En las primeras etapas de desarrollo, algunos desarrolladores de API se basarán únicamente en una colección de Postman para que sea una fuente suficiente de documentación para su API.
Este puede ser el caso, pero tan pronto como la API esté siendo utilizada por más personas que el único desarrollador con su única colección, esto se convierte rápidamente en una pesadilla.
Si tu API es pública, y no tiene documentación, nadie usará tu API en absoluto, lo que podría afectar drásticamente los éxitos de su empresa.
La integración con servicios a través de una API es un factor muy importante para muchas empresas en estos días, desde startups hasta grandes corporaciones, así que no te tomes la molestia de crear algo sorprendente solo para que lo ignoren por completo debido a la falta de documentación.
Te mostraré una forma de documentar tu API, ¿estás preparado?
Usa la sintaxis de API Blueprint:
FORMAT: 1A
# Encuestas
Encuestas es una API que permite a los clientes ver encuestas y votar en ellas.
# Group Preguntas
## Colección de preguntas [/preguntas]
### Lista todas las preguntas [GET]
+ Response 200 (application/json)
[
{
"pregunta": "¿Cuál es tu lenguaje de programación favorito?",
"publicado_en": "2014-11-11T08:40:51.620Z",
"url": "/preguntas/1",
"opciones": [
{
"opcion": "Go",
"url": "/preguntas/1/opciones/1",
"votos": 2048
}, {
"opcion": "PHP",
"url": "/preguntas/1/opciones/2",
"votos": 1024
}, {
"opcion": "Python",
"url": "/preguntas/1/opciones/3",
"votos": 512
}, {
"opcion": "Ruby",
"url": "/preguntas/1/opciones/4",
"votos": 256
}
]
}
]
El primer paso es especificar el formato, en nuestro ejemplo es 1A. es decir, la versión de API Blueprint.
FORMAT: 1A
En el primer encabezado colocamos el nombre de nuestra API, "Encuestas", los encabezados o títulos inician con uno o más numerales (#) seguidos de un espacio en blanco.
# Encuestas
El nivel del encabezado está dado por el número de numerales (#), es decir, un encabezado de nivel 2 tiene dos ("## ") al inicio.
Las líneas en general son considerados párrafos, es importante agregar una descripción de la API justo después del título.
Luego usamos la palabra clave "Group" para crear un grupo de recursos relacionados.
# Group Preguntas
Dentro del grupo "Encuestas" tenemos un recurso llamado "preguntas". El título especifica la URI usada para acceder al recurso, al final, dentro de paréntesis cuadrados.
## Colección de preguntas [/preguntas]
API Blueprint te permite especificar cada acción que puedes realizar en un recurso. Una acción es especificado como un subtítulo dentro del recurso con el nombre de la acción seguido por el método HTTP.
### Lista todas las preguntas [GET]
Una acción debe incluir al menos una respuesta del servidor que debe incluir un código de estado y puede contener un cuerpo. Una respuesta se define como un elemento de lista dentro de una acción. Las listas son creadas por elementos de lista precedentes con un +, * o -.
+ Response 200 (application/json)
[
{
"pregunta": "¿Cuál es tu lenguaje de programación favorito?",
"publicado_en": "2014-11-11T08:40:51.620Z",
"url": "/preguntas/1",
"opciones": [
{
"opcion": "Go",
"url": "/preguntas/1/opciones/1",
"votos": 2048
}, {
"opcion": "PHP",
"url": "/preguntas/1/opciones/2",
"votos": 1024
}, {
"opcion": "Python",
"url": "/preguntas/1/opciones/3",
"votos": 512
}, {
"opcion": "Ruby",
"url": "/preguntas/1/opciones/4",
"votos": 256
}
]
}
]
En nuestro ejemplo retornamos el código de estado 200 junto con un cuerpo JSON.
Te invito a leer la documentación de API Blueprint para que veas todas las posibilidades disponibles, para este ejemplo no agregaremos más cosas.
Aunque el archivo es legible, en cierto modo, a medida que vaya creciendo, puede resultar un poco difícil de comprender; vamos a crear un bonito HTML+CSS+JS para leer nuestra documentación cómodamente.
No, no tendremos que crear HTML a mano, usaremos Aglio, una herramienta de NodeJS que toma nuestro archivo ".apib" y lo transforma en una página web.
Para instalar Aglio, necesitamos tener NodeJS en nuestro sistema, luego ejecutamos el comando:
npm install -g aglio
Ahora ya podemos usar el comando aglio, le indicamos el nombre de nuestro archivo ".apib" con la bandera "-i" y el nombre del archivo donde se escribirá el HTML resultante con la bandera "-o":
aglio -i api_documentation.apib -o index.html
Al abrir index.html en nuestro navegador web veremos algo como esto:
En la web generada podemos expandir y contraer el cuerpo de la respuesta (Response) con el enlace show/hide.
Si no queremos el archivo HTML, podemos crear un servidor web que esté escuchando los cambios de nuestro archivo ".apib":
aglio -i api_documentation.apib --server
El comando arroja un mensaje similar a este:
Server started on http://127.0.0.1:3000/
Rendering doc.apib
Socket connected
Ahora cada vez que cambiemos nuestro archivo ".apib" tan sólo tendremos que ir al navegador a ver los cambios en http://127.0.0.1:3000.
Eso es todo por ahora futuro documentador de APIs, nos leemos en el siguiente artículo.
