Swagger

Swagger permite describir la estructura de sus API para que las máquinas puedan leerlas,
cuenta con la capacidad de las API para describir su propia estructura que es la raíz de
toda la genialidad en Swagger. También podemos generar automáticamente bibliotecas
de clientes para su API en muchos idiomas y explorar otras posibilidades, como las
pruebas automatizadas. Swagger hace esto pidiéndole a su API que devuelva un YAML
o JSON que contiene una descripción detallada de toda su API.

Swagger tambien nos ofrece una serie de reglas, herramientas y especificaciones que nos
ayudan a documentar nuestras APIs.

Uno de los objetivos de Swagger es que podamos actualizar la documentación en el

mismo instante en que realizamos los cambios en el servidor.

Dicha especificación se compone de dos partes:

 Resource Listing: devuelve un listado con todas las APIs a documentar/probar.

 API Declaration: devuelve la información relativa a un API, como sus
operaciones o el modelo de datos.

Con swagger puedes describir, producir, consumir y visualizar APIs, por lo que te será
interesante como desarrollador de tu proyecto, pero también desde el punto de vista de un
tercero que pudiese consumir tu API, o un usuario que busca información sobre un error
o como tu API está construida, o un tester de tu equipo que quiere probar la funcionalidad
de backend como primera medida para excluir un fallo en esta lado para centrarse en
Frontend o no.
 Ilustración 1 Mapa de construcción de Swagger

Swagger UI

Swagger UI es una de las herramientas atractivas de la plataforma. Para que una

documentación sea útil necesitaremos que sea navegable y que esté perfectamente
organizada para un fácil acceso. Por esta razón, realizar una buena documentación puede
ser realmente tedioso y consumir mucho tiempo a los desarrolladores.

Swagger UI utiliza un documento JSON o YAML existente y lo hace interactivo. Crea

una plataforma que ordena cada uno de nuestros métodos (get, put, post, delete) y
categoriza nuestras operaciones. Cada uno de los métodos es expandible, y en ellos
podemos encontrar un listado completo de los parámetros con sus respectivos ejemplos.
Incluso podemos probar valores de llamada.
 Ilustración 2 página de inicio de Swagger UI

Swagger Editor

Swagger Editor es un editor de código abierto para diseñar, definir y documentar API
RESTful en la especificación Swagger. Swagger Editor puede ejecutarse localmente o
accederse en la Web. SwaggerHub trae las herramientas Editor de Swagger, UI y Codegen
a la nube en un diseño y documentación API integrados, creados para equipos API que
trabajan con la especificación Swagger (OpenAPI).
 Ilustración 3 Aplicación Swagger Editor

Balanceo de carga

El Balanceo de Carga es la distribución de la actividad de procesamiento y la

comunicación de manera uniforme a través de una red informática a fin de que no exista
ningún aparato está «sobrecargado». El balanceo de carga es especialmente importante
para las redes en las que es difícil predecir el número de solicitudes que se enviarán a un
servidor. Muchos sitios web con gran tráfico suelen utilizar dos o más servidores con un
esquema de balanceo de carga, esto permite que cuando un servidor está muy saturado de
solicitudes, automáticamente los usuarios son redirigidos a otro servidor con más
capacidad de respuesta en ese momento.

Arquitectura de Ribbon

Ribbon utiliza básicamente dos elementos a la hora de decidir cuál será la instancia a la
que finalmente derivará la petición, estos dos elementos son los balanceadores (con sus
filtros asociados) y las reglas.

Así, en primer lugar, Ribbon utilizará un balanceador y filtros para descartar una serie de
instancias del microservicio a invocar, en base a diversos criterios: que las instancias estén
caídas, que estén en una zona con una alta carga de peticiones…
Una vez pasada esta primera etapa quedarán una serie de instancias que son las que
cumplen las condiciones implementadas en los filtros, y ahí entrarán en juego las reglas
de balanceo para determinar a cuál de esas instancias enviar la petición.

Ribbon dispone de diferentes filtros y reglas, así como la posibilidad de implementar los
que deseemos, cosa que haremos en las siguientes secciones.

Funcionamiento en Ribbon

Para demostrar su funcionamiento el cliente realiza varias llamadas a un servicio cada

uno, pocos milisegundos balanceando la carga entre las instancias que existan. Si con
posterioridad se añade una nueva instancia del servicio Ribbon al cabo de un tiempo de
que haya sido iniciada lo añadirá a la lista y empieza a seleccionarla para enviarle
peticiones. Si una instancia falla hasta que Eureka no marca la instancia como fuera de
servicio y el cliente no actualiza su lista de instancias en el ejemplo de cliente seguirá
enviando peticiones a la instancia fuera de servicio y con Hystrix utilizando el método de
fallback como respuesta.

El cliente usa la clase LoadBalancerClient que en cada invocación del método choose ()
devuelve una instancia diferente de servicio realizando balanceo de carga utilizando el
método round-robin. La clase ServiceInstance proporciona la URL de la instancia del
servicio.
 Ilustración 4 Creación del package

Ilustración 5 Construcción de la clase ClientService para el balanceo

 Ilustración 6 Demostración de los plugins

La clase del servicio y los comandos para iniciar el servicio de registro y descubrimiento,
el servicio de configuración, las instancias del servicio en diferentes puertos y el cliente.

Ilustración 7 configuración de las instancias del servicio

Ilustración 8 Configuración de los puertos

Esta es la salida y funcionamiento del cliente realizando balanceado la carga entre las
múltiples instancias y que ocurre cuando se añade una nueva o una empieza a fallar y se
elimina de la lista.

Ilustración 9 Demostración del respectivo balanceo

Ribbon posee numerosas propiedades de configuración a nivel global para todos los
clientes de servicios o de forma específica para cada servicio ya sea con la anotación
@RibbonClient o mediante la configuración en archivos externos de Spring Boot.
Algunas propiedades de configuración interesantes son las de timeout que permiten que
un cliente no agote sus recursos esperando a que a los servicios que llama si tardan en
responder y a su vez el cliente actuando de servidor recibe muchas llamadas de sus
clientes.
Servidor de Autorización

Para configurar un cliente oauth deberemos especificar:

 withClient. Id del cliente

 secret. Password del cliente
 authorizedGrantTypes. Tipo de permisos que le permitirán realizar operaciones
en el proceso de autenticación oauth así como en la generación de tokens
 scopes. Ámbitos o conjunto de recursos, que los usuarios que se integran vía
oauth, conceden al cliente para consultar sus datos.
 redirectUris. Url a la que se redirige una vez el proceso de autenticación oauth
haya finalizado.
 accessTokenValiditySeconds. Tiempo en el que el access token es válido
 refreshTokenValiditySeconds. Tiempo en el que el refresh token es válido

Ilustración 10 servidor de recursos

Asignamos el orden para el filtro del servidor de recursos a 3. Según la release de Spring-
Boot-1.5 se cambió de 3 a SecurityProperties.ACCESS_OVERRIDE_ORDER - 1 en esta
versión. Es necesario cambiarlo a 3 ya que al acceder a las apis del servidor a través del
token de acceso es necesario que este filtro salte antes que el filtro de seguridad por
defecto. Es necesario cambiarlo a 3 ya que al acceder a las apis del servidor a través del
token de acceso es necesario que este filtro salte antes que el filtro de seguridad por
defecto.
 Ilustración 11 Cambio de filtro a 3

Ahora se probará la aplicación donde el proceso de autenticación oauth empieza

mostrándole al usuario el formulario de login de la aplicación que queremos integrar.
Debemos ejecutar la siguiente URL en el navegador indicando los siguientes parámetros

 El id del cliente
 La URL de redirección

Ilustración 12 Dirección URL

Ilustración 13 Procedemos a logarnos con un usuario del sistema

Ilustración 14 Pantalla de aprobación en donde el usuario concede permisos al cliente my-trusted-client para
acceder a sus recursos.
Ilustración 15 URL de redirección asociada a nuestro cliente pasando el parámetro code.
Conclusión
La practica con microservicios ayuda mucho al desarrollo de aplicaciones y se construyen
con pequeños servicios con lo que se comunican con mecanismos ligeros que proveen
ayuda al desarrollador. Las implementaciones que se tratan en este documento ayudan
mucho ya que trabajan con el lenguaje de java, JSON y otros mas y esto abre a la idea en
que estos lenguajes marcan una idea a la hora del desarrollo de aplicaciones o de
demostrar un balanceo en nuestras redes o tener seguridad en nuestro trabajo, sino que
abre a la idea del programador a innovarse a la medida de crear nuevos programas,
aplicaciones y mantener mas seguro el trabajo que desarrollamos.

Con el servicio Swagger se tiene ventajas de trabajar con nuestras APIs ya que tiene reglas
que nos lleva a desarrollarlas de manera amplia, segura y cuenta con diversas
herramientas que nos ayuda a conocer más del trabajo que estamos realizando en nuestra
aplicación.

Preguntas
¿Cuál es el funcionamiento de Ribbon?

a) No trabaja directamente con Spring boot.

b) El cliente realiza varias llamadas a un servicio cada uno, pocos milisegundos
balanceando la carga entre las instancias que existan.
c) Se debe asegurar las direcciones IP correspondientes.
d) Mantiene el trabajo con pocas instancias y añade una salida.

Glosario
YAML: Es un formato de serialización de datos legible por humanos inspirado en
lenguajes como XML, C, Python, Perl, así como el formato para correos electrónicos
especificado en RFC 2822 (publicaciones RFC).

API: es un conjunto de funciones y procedimientos que cumplen una o muchas funciones

con el fin de ser utilizadas por otro software. Las siglas API vienen del inglés Application
Programming Interface. En español sería Interfaz de Programación de Aplicaciones.

TESTER: Es un instrumento eléctrico portátil para medir directamente magnitudes

eléctricas activas, como corrientes y potenciales (tensiones), o pasivas, como resistencias,
capacidades y otras.
SOBRECARGA: Es la capacidad de un lenguaje de programación, que permite nombrar
con el mismo identificador diferentes variables u operaciones. En programación orientada
a objetos la sobrecarga se refiere a la posibilidad de tener dos o más funciones con el
mismo nombre, pero funcionalidad diferente.

OPENAPI: Es una especificación para archivos de interfaz legibles por máquina para
describir, producir, consumir y visualizar servicios web RESTful.

Referencias
Chakray. (27 de Enero de 2017). SWAGGER Y SWAGGER UI: ¿QUÉ ES Y POR QUÉ ES
IMPRESCINDIBLE PARA TUS APIS? Obtenido de Chakray:
https://www.chakray.com/es/swagger-y-swagger-ui-por-que-es-imprescindible-para-
tus-apis/

Fernandez, Luis. (24 de Diciembre de 2018). Cómo documentar nuestras APIs con Swagger.
Obtenido de Medium: https://medium.com/@lfernapalacio/c%C3%B3mo-
documentar-nuestras-apis-con-swagger-1eca6d5524a8

Jorge Hernandez Ramirez. (17 de Abril de 2017). Spring Boot – OAuth Server. Obtenido de
jorgehernandezramirez:
https://www.jorgehernandezramirez.com/2017/04/17/spring-boot-oauth-server/

picodotdev. (12 de Diciembre de 2018). Balanceo de carga y resilencia en un microservicio con

Spring Cloud Netflix y Ribbon. Obtenido de picodotdev:
https://picodotdev.github.io/blog-bitix/2018/10/balanceo-de-carga-y-resilencia-en-
un-microservicio-con-spring-cloud-netflix-y-ribbon/

Rodríguez, A. (2 de Diciembre de 2015). Ribbon: el balanceador de carga de spring-cloud-

netflix (1/3) . Obtenido de Paradigma: https://www.paradigmadigital.com/dev/ribbon-
balanceador-carga-spring-cloud-netflix-13/

SMARTBEAR SOFTWARE. (2019). What is Swagger. Obtenido de Swagger:

https://swagger.io/docs/specification/2-0/what-is-swagger/