En el capítulo anterior, se presentó Swagger y cómo trabajar con él. En este capítulo, exploraremos su uso a través de un ejemplo práctico y completaremos por completo nuestra primera API REST.

Introducción a Swagger

En el video, se presentó la interfaz principal de Swagger y cómo interactuar con ella.

Para los métodos que aceptan un cuerpo de solicitud, Swagger genera automáticamente JSON basado en el objeto que recibe el endpoint actual.

Además, si tienes parámetros en la URL, puedes especificarlos fácilmente en los campos correspondientes.

Swagger también muestra los posibles códigos de estado para el endpoint y especifica el tipo de retorno del objeto (JSON/XML).

Y lo más importante: ¡no tuviste que escribir ningún código adicional para generar esta documentación!

Simplemente con agregar la dependencia y configurarla si es necesario (aunque a menudo no se requiere configuración) es suficiente para obtener automáticamente la documentación de tu REST API.

Trabajo con anotaciones

Revisión breve de las anotaciones tratadas en este capítulo:

@Tag – Agrupa endpoints relacionados y les añade una descripción.

@Operation – Describe un método API específico, incluyendo su propósito y una breve descripción.

@Parameter – Describe los parámetros del método, como variables de ruta, parámetros de consulta, entre otros.

@ApiResponse – Describe una única posible respuesta específica, incluyendo el código de respuesta y su descripción.

@ApiResponses – Define un conjunto de posibles respuestas para el método, incluyendo códigos de estado y descripciones.

Proyecto

También proporciono un enlace al proyecto en caso de que algo no funcione o si desea explorarlo en mayor detalle:

Resumen

Swagger permite la generación automática de documentación detallada para su API, facilitando su uso y pruebas.

Con anotaciones como @Operation, @ApiResponse y @Parameter, es posible describir el comportamiento de métodos, parámetros y posibles respuestas sin agregar código adicional. Esto hace que su API REST sea más clara y accesible para los desarrolladores.