Introducción a Swagger

Swagger es un conjunto de herramientas de software de código abierto diseñadas para ayudar a los desarrolladores a diseñar, construir, documentar y consumir servicios web RESTful. Su objetivo principal es simplificar el desarrollo y la documentación de API (Application Programming Interface) para que sean más accesibles y fáciles de entender para los desarrolladores.

¿Qué es Swagger?

Swagger proporciona una especificación estándar para describir APIs RESTful. Esta especificación, conocida como OpenAPI Specification (OAS), permite a los desarrolladores describir de manera clara y precisa los endpoints de la API, los métodos HTTP disponibles (GET, POST, PUT, DELETE, etc.), los parámetros de entrada y salida, los tipos de datos utilizados.

Componentes Principales de Swagger

1. Swagger Editor: Una herramienta de edición en línea que permite a los desarrolladores crear y editar especificaciones de API en formato YAML o JSON.
2. Swagger UI: Una interfaz gráfica interactiva que genera documentación visual de las API a partir de una especificación OpenAPI. Los desarrolladores pueden probar las llamadas a la API directamente desde la documentación generada, facilitando la comprensión y el uso de la API.
3. Swagger Codegen: Una herramienta que permite generar código cliente y servidor en varios lenguajes de programación a partir de una especificación OpenAPI.
4. Swagger Hub: Una plataforma colaborativa que permite a los equipos de desarrollo trabajar juntos en el diseño, documentación y mantenimiento de sus APIs.

Cómo Funciona Swagger

1. Diseño de la API: Los desarrolladores comienzan creando una especificación OpenAPI en formato YAML o JSON. Esta especificación describe todos los detalles de la API, incluyendo los endpoints, métodos, parámetros, esquemas de respuesta, y más.
2. Documentación: Una vez que se ha creado la especificación, Swagger UI se puede usar para generar una documentación interactiva y visual. Esta documentación permite a los usuarios explorar y probar los endpoints de la API directamente desde el navegador.
3. Generación de Código: Con Swagger Codegen, los desarrolladores pueden generar automáticamente clientes y servidores en diversos lenguajes de programación basados en la especificación de la API. Esto facilita la implementación y el consumo de la API en diferentes entornos.
4. Colaboración: Usando Swagger Hub, los equipos de desarrollo pueden trabajar juntos en la especificación de la API, revisando cambios, proporcionando comentarios y asegurando que la API cumpla con los requisitos y estándares establecidos.

Cómo instalar Swagger con la última Versión en Spring boot

Paso 1: Comprende las diferencias:

Antes de realizar la actualización, es crucial revisar las notas de la versión y la documentación para comprender las diferencias entre la versión que tienes y la última.

Paso 2: Actualizar el archivo pom.yaml:

Asegúrate de tener definida la dependencia correcta para Swagger 3.0 en el bloque de dependencias de tu proyecto. para esto agregaremos la siguiente librería a nuestro archivo pom.xml:

Esto es una biblioteca para integrar Swagger UI con spring boot, lo que permitirá generar la documentación necesaria para OpenAPI.

• groupId: es el identificador del grupo al que pertenece la biblioteca en el repositorio de Maven, en este caso pertenece al grupo “org.springdoc“
• ArtifactId: es el identificador único de la biblioteca dentro del grupo, en este caso la biblioteca se llamas springdoc-openapi-ui.
• Version: aquí especificamos la versión que usaras en el proyecto en este caso sería la versión 1.6.15

Paso 3: Eliminar la librería SpringFox

En el archivo pom.xml eliminaremos la librería:

Se eliminará esta biblioteca es porque utiliza versiones anteriores a Swagger 3.0, para nuestra nueva versión usaremos las bibliotecas mencionadas en el paso 2.

Paso 4: Eliminar el archivo SwaggerConfig                                                                                                                          Este archivo se encuentra dentro del archivo src/main/java/config.java.

Paso 5: Agregar código para Configurar y definir OpenAPI

Nos ubicaremos src/main/java/   buscaremos el archivo que diga MicroservicioNombreDelMicro o microNombreDelMicro y agregaremos las siguientes líneas de código.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.servers.Server;

@OpenAPIDefinition(info = @Info(title = "Microservicio nameMS",
version = "1.0.3",
description = "APIs Swagger Microservicio nameMS",
license = @License(name = "Apache 2.0",
contact = @Contact(url = "S", name = "MS-nameMS", email = "")),
security = {@SecurityRequirement(name = "") },
servers = {
@Server(description = "ambiente local", url = "http://localhost:8080/"),
@Server(description = "url ambiente dev expuesta por Apigateway", url = ""),
@Server(description = "url ambiente qa expuesta por Apigateway", url = "https://"),
@Server(description = "url ambiente prod expuesta por Apigateway", url = "https:/")

}
)
@SpringBootApplication
@EnableAsync
@EnableConfigurationProperties({ApplicationProperties.class})
public class NameMS{

	public static void main(String[] args) {
		SpringApplication.run(NameMS.class, args);
	}

}

Este código se utiliza en la configuración y define la documentación de la API basada en OpenAPI, a continuación, se explicará las diferentes partes de las anotaciones y su propósito:

@OpenAPIDefinition: Esta anotación se coloca en la clase principal, se utiliza para definir la información general de la API, contiene los siguientes parámetros:

• info: Aquí se proporciona información de la API, como el título de tu Microservicio, versión y descripción.
• license: Permite especificar la licencia la cual se distribuye la API, como el ‘name’ y una ‘url’ para más detalles.
• contact: Aquí proporcionaremos información sobre el equipo, donde en la url incluiremos la información del microservicio en el que estemos trabajando.

Paso 6: Agregar código en Application.yaml

openapi:
  expand:
    api:
      version: v1.1

Paso 7: Agregar detalles a la interface del controller.

Anotaciones:

• @Operation → Nombre del endpoint, descripción del mismo y además nombre del microservicio.
• @Parameter → Parámetros de entrada para el endpoint. En el name debe tener el mismo nombre que trae en el endpoint (Ejemplo: en el endpoint esta así → /{id}/→ en el name debe decir name = “id“).
• @ApiResponses → Acá se indican las respuestas que tiene en la implementación del controller. Si hay alguna respuesta que responde 200 pero viene vacía acá hay que dejarla como 204 y con la descripción que se indica en el código, ya que algunos casos piden que aunque no vengan datos se muestre una respuesta correcta, pero sin data.

Ejemplo de como se debe hacer:

package cl.microservicio.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

public interface Controller {
    @Operation(summary = "...", description = "Endpoint que trae los datos de la solicitud", tags={ "nombre de tu microservicio" }	)
    @Parameter(name = "id", description = "", example = "", required = true)
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Consulta Generada Correctamente."),
        @ApiResponse(responseCode = "204", description = "No se han encontrado datos para el id consultado."),
        @ApiResponse(responseCode = "500", description = "Error en la consulta")
    })

}

Para corroborar que todo este bien, debemos levantar el microservicio localmente y en el navegador abrir la siguiente url: http://localhost:8080/swagger-ui/index.html# . Si todo esta bien, podrás ver la descripción de tus endpoints.

ULTIMO PASO:

En el link antes abierto encontraras en la esquina superior izquierda el link marcado en rojo, que te abrira en una nueva pestaña un JSON que debe ser transformado al formato YAML (puedes usar el siguiente link: JSON to YAML Converter Online Tool  y lo que se genere lo debes guardar en un nuevo archivo ubicado en la raíz del microservicio llamado swagger.yaml

‍

Ventajas de Usar Swagger

• Estándar Abierto: Swagger utiliza la especificación OpenAPI, un estándar abierto ampliamente aceptado para describir APIs RESTful.
• Documentación Clara: Proporciona una documentación interactiva y fácil de entender, lo que facilita a los desarrolladores y usuarios comprender cómo interactuar con la API.
• Productividad: La generación automática de código cliente y servidor ahorra tiempo y reduce errores, permitiendo a los desarrolladores centrarse en la lógica del negocio.
• Colaboración: Facilita la colaboración entre equipos de desarrollo, asegurando que todos los miembros trabajen con una visión clara y coherente de la API.

En resumen, Swagger es una herramienta poderosa que facilita el diseño, documentación y consumo de APIs RESTful, mejorando la productividad y colaboración en equipos de desarrollo.

¿Listo para mejorar la documentación y prueba de tus APIs RESTful?

En Kranio, contamos con expertos en desarrollo backend y documentación de APIs que te ayudarán a implementar soluciones eficientes utilizando Swagger y Spring Boot, asegurando que tus servicios sean fácilmente comprensibles y probables. Contáctanos y descubre cómo podemos impulsar la calidad y eficiencia de tus desarrollos.