Resumen

Con el tiempo los sistemas desacoplados han proliferado, y la integración con ellos es cada vez
más frecuente, por lo que las personas que realizan la integración deben informarse de cómo se
utilizan esas API y evitar la iteración en el intento, dado que no cuentan con una visibilidad
suficiente de su uso y su integración, y para disminuir esta brecha es importante contar con una
buena documentación.

Objetivo
La presente Wiki pretende ser parte de la base de conocimiento de Arquitectura dando una vista
al producto Swagger, revisando las principales funcionalidades y su usabilidad.

Alcance
Swagger

 Instalación
 Diseñando API
 Probando API
 API de ejemplo

Introducción

Swagger
Este es un producto de código abierto para el diseño de API de manera ágil, permitiendo entre
otras cosas:

 Documentación (Especificación OpenAPI) para entenderla de manera que otros

programadores puedan entenderla, logrando acelerar los tiempos de desarrollo y de
consumo.
 Está integrada en JHipster al momento de consultar la documentación de la API de los
Microservicios.
 En una etapa temprana podemos diseñar nuestras API con Swagger Editor, que tiene
una interfaz intuitiva y fácil de usar.

Swagger Editor – Instalación

Mediante git clone el proyecto de Swagger Editor desde la siguiente
URL: https://github.com/swagger-api/swagger-editor

 
 

1. Cree un directorio llamado Swagger Editor y mediante un CMD ejecute el siguiente

comando:
C:\Instaladores\Swagger Editor>git clone https://github.com/swagger-api/swagger-
editor

2. Mediante un Explorador de Internet (en mi caso Google Chrome) abra el archivo html
que se encuentra en la raíz del proyecto.

 
En mi caso me cree un Acceso Directo al archivo:
file:///C:/Instaladores/Swagger%20Editor/swagger-editor/index.html
Entonces se abrirá el programa Swagger Editor con un ejemplo cargado por default. En mi caso
yo estoy trabajando con otro proyecto.
 

 
 

Swagger Editor – Diseñando API

En el proyecto Microservicio ncalite-conductores del archivo pom.xml que se encuentra en la raíz
del proyecto está declarado el uso del artefacto openapi.
 

 
Aquí se especifica la construcción de un archivo tipo YAML, llamado api.yml que contiene la
especificación de nuestra API del Microservicio.
Volvamos a Swagger Editor y mediante el menú principal limpiamos el editor con la opción
File/Clear Editor.

 
Ahora importemos el archivo api.yml.
 
Inmediatamente Swagger generará la documentación respecto a la API.

 
Al hacer clic en el botón celeste POST, se desplegará el detalle para el entendimiento del
consumo de esta API.
 
 
En el lado izquierdo se puede modificar y el lado derecho documentará los cambios realizados en
el lado izquierdo. Si introducimos un error, Swagger Editor nos informa. En la línea 6 donde dice
schemes voy a quitar una “s” y dejar scheme.

 
Entonces solo basta con diseñar la API. Agreguemos otro esquema, el HTTP en la línea 7.

 
El lado derecho documenta el cambio.

 
Más adelante revisaremos en más detalle la especificación OpenAPI.
Salvemos el archivo como YAML.
 

 
Entonces en el directorio definido para las descargas dejará un archivo llamado swagger.yaml
con la misma especificación definida en el archivo api.yml, la diferencia estaría en la primera
línea que es reservada para decir cómo se creó.
 
 
En este caso muestro el de otro proyecto, pero inicialmente era así:

 
La idea es reemplazar este archivo por el nuevo que es generado mediante Swagger Editor y
regenerar el proyecto mediante el siguiente comando:
C:\Proyectos\ncalite\ncalite-conductores>mvnw generate-sources
 
También te da la opción de convertirlo y salvarlo como JSON:

 
Entonces igual que antes descargará un archivo JSON llamado swagger.json

 
Arrastramos el archivo hasta el área donde dice Drop files here o lo buscamos presionando el
botón Choose Files.
 
Entonces Postman agregará un grupo donde el nombre del grupo corresponde al valor del
campo title.

 
 
 
 

Postman – Probando la API del Microservicio

Para hacer una prueba es muy fácil, ya que simplemente levantamos los Microservicio en el
orden Restry, Gateway y el Microservicio que estamos trabajando. Una vez que todo este arriba,
abrimos Postman e importamos el archivo el archivo api.yml que se encuentra en nuestro
proyecto.
NOTA: Recordemos que este archivo fue reemplazado por el archivo swagger.yaml  generado por
Swagger y también hemos regenerado el proyecto como se explicó anteriormente.
 
Entonces Postman creará un grupo que contendrá las distintas invocaciones a la API a partir de
la descripción del mismo:

 
Note que el nombre del grupo creado corresponde a la etiqueta title y la descripción
del GET corresponde a la etiqueta sumary.

 
 
 

Diseñando API reserva de libro

Mediante el menú limpiamos el Swagger Editor

 
La primera línea específica la herramienta con lo cual se generó el diseño. En este caso vamos a
seleccionar swagger. Fíjese que al presionar la letra “s” ya te lo propone. Seleccione con el
mouse o presione enter.

 
Fíjese que en el lado derecho está reclamando que le falta la etiqueta info, bueno agreguémosla.
 
Entonces agrega una seria de etiquetas por defecto, y nos da cuenta de la licencia entregada.
Entonces nos dirigimos a la URL indicada https://opensource.org/licenses/MIT

 
Al presionar el botón “Más recursos en la licencia MIT” nos indica otras licencias al respecto.

 
Personalmente me llama la atención por la palabra MIT ya que yo la relaciono con el Instituto
Tecnológico de Massachusetts, por el cual voy a investigar un poco más. Al indagar más al
respecto vemos que es una licencia para código abierto creada por esta institución de fama
mundial creada en el año 1980, que es muy difundida incluso un resportaje por que fue incluida
para el uso de la moneda Bitcoin.
Continuando con nuestra prueba definimos los campos necesarios, tales como version, title,
description.
 
Vemos que Swagger nos está reclamando la falta de información de contacto en la línea 7.

 
Agregamos la información de contacto faltante.
 
Ahora me reclama que falta la información en relación al paths

.
 
 
Antes de agregar el path vamos a agregar los esquemas (schemes):

 
Agregamos el path. Considere que si el titulo Libros es en plural el obtener la información de un
libro debería ser en singular o sea libro. Al momento de escribir la etiqueta get, autogenera lo
faltante:
 
Fíjese que, al momento de autocompletar, el cursor aun esta sobre la palabra get. Completamos
los datos faltantes:

 
Ya no tenemos errores en nuestra estructura:
 
Definamos ahora una estructura de datos tanto de entrada como de salida

 Datos de entrada
o Código del Libro: Es el código único para identificar un libro
 Datos de salida
o Habilitación: Es un enumerador donde puede ser:
 DISPONIBLE
 RESERVADO
o Autor: Nombre del autor
o Género: Es un enumerador donde puede ser
 NOVELA
 CIENCIA
 HISTORIA
o Ubicación: Código compuesto de la repisa (aparador), gaveta dentro de la repisa
donde se encuentra el libro.

 
Agregamos primero el dato de entrada codigoLibro:
 
Fíjese en la etiqueta parameter donde declaramos la variable y luego la especificamos en la
etiqueta definitions. Esto es un simple string, pero en la respuesta agreguemos un objeto que
contenga toda la estructura antes definida.
 
Vemos los cambios en el object de salida HabilitacionLibro:

 
Fíjese que la documentación quedo completa, tanto en los parámetros de entrada como los de
salida:

 
 

Referencias
https://github.com/swagger-api/swagger-editor