Documentando APIS con Swagger

A medida que nuestra api crece también crece la necesidad de documentarla, pues en el mundo del desarrollo, el trabajo en equipo es nuestro pan de cada día y no desarrollamos para nosotros mismos.

Pero, ¿Por qué es importante documentar una API?

• Facilita el desarrollo para otros desarrolladores.
• Incrementa la productividad.
• Simplifica la búsqueda.
• Mejora el mantenimiento del código.

Dentro de todas las herramientas disponibles para la documentación de una API, hoy vamos a hablar de Swagger. Una plataforma colaborativa donde poder documentar y compartir la documentación de nuestras APIs.

¿Por qué Swagger?

Dentro de todas las herramientas disponibles para la documentación de una API, hemos elegido Swagger, que es una plataforma colaborativa donde podemos definir las peticiones, la seguridad y los parámetros de los métodos de las APIs con una sintaxis muy parecida a un JSON. A la hora de trabajar con el editor, encontramos 3 zonas bien definidas, la navegación, el editor de texto, y la interfaz, que se genera a medida que escribimos el código. Estas secciones se pueden cerrar o abrir a nuestra voluntad, lo que genera una interfaz muy limpia y usable.

A continuación se explicarán algunas de las características mas importantes a la hora de documentar una API con el editor de Swagger. Empezaremos hablando de los esquemas y la seguridad, para acabar haciendo peticiones a los endpoints indicando que parámetros se utilizarán y que respuesta dará el servidor.

Esquemas

Dentro de Swagger podemos encontrar los esquemas, o modelos de datos. Son componentes que podemos reutilizar para no repetir información dentro de la documentación. Los esquemas se sitúan en la propiedad components del documento.
Estos esquemas nos permiten definir un modelo que será enviado al servidor, o recibido del mismo. El atributo más básico de los modelos es denominado type, este nos permite identificar si el modelo será un número, una cadena de texto, un arreglo de datos, un booleano, o un objeto.

¿Y ya está? No, obviamente no es el único atributo que se puede definir. Swagger nos permite indicar si la propiedad es requerida, su longitud máxima, mínima, un patrón, una descripción e incluso su valor por defecto. Dentro de estos, también se puede hacer referencia a otros modelos utilizando la propiedad $ref como se muestra en este ejemplo:

Seguridad

Swagger utiliza el termino esquema de seguridad para la autorización y los esquemas de autorización. Estos son algunos de los esquemas que la última versión de este software nos permite emplear:

• Http:
  • Basic.
  • Bearer.
• Api Keys:
  • Autenticación mediante cookies.
• OAuth.

Podemos configurar más de un tipo de seguridad e implementarla de manera global, o método a método. En este ejemplo hemos utilizado el esquema Http, el cual hemos definido dentro de la sección securitySchemes, que está, a su vez, dentro de la sección components:

Para utilizar este esquema en las peticiones, debemos indicarlo dentro del endpoint:

Para introducir el token en la cabecera de la petición, tendremos que pulsar el botón Authorize que aparece en la sección de la documentación.

Esto nos permitirá utilizar el mismo token en todas las peticiones que requieran del mismo.

Peticiones

Una de las principales características de la documentación es la definición de los endpoints y de los parámetros, los cuales veremos en la siguiente sección.

Para definir un endpoint tenemos que ir a la sección path, la cual está en la raíz del documento, y ahí, establecer el endpoint. Algunas de los atributos que podemos especificar son los siguientes:

• Resumen.
• Descripción.
• Respuesta.
• Parámetros.
• Seguridad.
• Cuerpo de la petición.

En el siguiente ejemplo se indica el método post al endpoint /auth/login, se añade el tipo de respuesta que puede generar el servidor, junto con una descripción de esta, además podemos indicar de manera explícita qué valores devolverá la API.

Dentro del atributo requestBody, se indica que se enviará un modelo del tipo LoginCredentials.

Todo este código generará una interfaz en la zona de la documentación que se verá de la siguiente manera.

Aquí se muestra de una manera más clara las características de la petición. Además, si se pulsa el botón Try it out, se hará una llamada a dicho endpoint con el cuerpo que nosotros deseemos.

Parámetros

Dentro de la sección de las peticiones, podemos describir un parámetro, y con este, su descripción, su nombre, su obligatoriedad, etc.

Los parámetros pueden proceder de diferentes puentes, por eso es necesario indicar su procedencia en el atributo in. Dentro de este atributo podemos indicar si el dato se enviará en la cabecera de la petición, como querystring, como una cookie, o irá en la uri.

En el siguiente caso se muestra un endpoint que necesita dos parámetros en la uri:

Para emplear un sistema de paginación, o un filtro, lo más común es utilizar el querystring, y cómo estos parámetros no suelen ser requeridos, es normal tener valores por defecto.

Respuestas

Junto con los parámetros se pueden especificar las diferentes respuestas que puede proveer el servidor. De estas podemos indicar su código de estado, por ejemplo el código 202 es el código utilizado para indicar que un elemento se ha actualizado correctamente, o el 401 para indicar que el usuario no está autorizado.

Las respuestas van dentro de los endpoint, y su sintaxis es la siguiente:

Como se puede observar, el código marca el inicio de su sección, y dentro podemos señalar cuáles serán las cabeceras que enviará la API. En este caso, la API que utilizo para hacer el ejemplo devuelve una cabecera llamada paginación, la cual sigue el siguiente esquema como indica en su propiedad $ref:

Al indicar todas estas características en la petición, se genera una interfaz en la que se ve de manera más limpia.

Hasta aquí las características más importantes del editor de Swagger. Sin duda una herramienta a tener en cuenta a la hora de documentar una api. Su sintaxis es fácil de aprender, muy similar al formato JSON, y su interfaz muy limpia e intuitiva.

Autor: Guillermo Priego Sierra

Curso: Microsoft MCSA Web Applications + Microsoft MCSD App Builder + Xamarin

Centro: Tajamar

Año académico: 2018-2019

Código / recursos utilizados / Otros datos de interés:
Documentación