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.

BookController.java


              1234
            
@Tag(name = "Books", description = "API for managing books")
public class BookController {
    // struct
}

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

BookController.java


              1234
            
@Operation(summary = "Get a list of all books", description = "Returns a list of all available books")
public List<BookResponseDTO> getAllBooks() {
    return bookService.findAllBooks();
}

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

BookController.java


              12345
            
public BookResponseDTO getBookById(
        @Parameter(description = "ID of the book to retrieve", required = true)
        @PathVariable String id) {
    return bookService.getBookById(id);
}

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

BookController.java


              12345678
            
@ApiResponse(responseCode = "204", description = "Book successfully deleted")
@DeleteMapping("/{id}")
public void deleteBook(
    @Parameter(description = "ID of the book to delete", required = true)
  	@PathVariable String id
) {
    	bookService.deleteBook(id);
}

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

BookController.java


              12345678910111213
            
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Book successfully updated"),
        @ApiResponse(responseCode = "404", description = "Book not found")
})
@PutMapping("/{id}")
public BookResponseDTO updateBook(
  		@Parameter(description = "ID of the book to update", required = true) 
		@PathVariable String id,
  @RequestBody(description = "Updated book details", required = true) BookRequestDTO book
) {
    return bookService.updateBook(id, book);
}

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.

¿Todo estuvo claro?

¡Gracias por tus comentarios!

Sección 3. Capítulo 7

Pregunte a AI

Pregunte lo que quiera o pruebe una de las preguntas sugeridas para comenzar nuestra charla

Awesome!

Completion rate improved to 3.45

Desliza para mostrar el menú

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!

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.

BookController.java


              1234
            
@Tag(name = "Books", description = "API for managing books")
public class BookController {
    // struct
}

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

BookController.java


              1234
            
@Operation(summary = "Get a list of all books", description = "Returns a list of all available books")
public List<BookResponseDTO> getAllBooks() {
    return bookService.findAllBooks();
}

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

BookController.java


              12345
            
public BookResponseDTO getBookById(
        @Parameter(description = "ID of the book to retrieve", required = true)
        @PathVariable String id) {
    return bookService.getBookById(id);
}

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

BookController.java


              12345678
            
@ApiResponse(responseCode = "204", description = "Book successfully deleted")
@DeleteMapping("/{id}")
public void deleteBook(
    @Parameter(description = "ID of the book to delete", required = true)
  	@PathVariable String id
) {
    	bookService.deleteBook(id);
}

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

BookController.java


              12345678910111213
            
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Book successfully updated"),
        @ApiResponse(responseCode = "404", description = "Book not found")
})
@PutMapping("/{id}")
public BookResponseDTO updateBook(
  		@Parameter(description = "ID of the book to update", required = true) 
		@PathVariable String id,
  @RequestBody(description = "Updated book details", required = true) BookRequestDTO book
) {
    return bookService.updateBook(id, book);
}

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.

¿Todo estuvo claro?

¡Gracias por tus comentarios!

Sección 3. Capítulo 7

Pruebas de API RESTful

Introducción a Swagger

Trabajo con anotaciones

Proyecto

Resumen

Awesome!

Pruebas de API RESTful

Introducción a Swagger

Trabajo con anotaciones

Proyecto

Resumen