No capítulo anterior, fomos apresentados ao Swagger e como trabalhar com ele. Neste capítulo, exploraremos seu uso por meio de um exemplo prático e iremos finalizar nossa primeira REST API!

Introdução ao Swagger

No vídeo, você foi apresentado à interface principal do Swagger e como interagir com ela.

Para métodos que aceitam um corpo de requisição, o Swagger gera automaticamente o JSON com base no objeto que o endpoint atual recebe.

Além disso, se houver parâmetros na URL, é possível especificá-los facilmente nos campos correspondentes.

Swagger também exibe os possíveis códigos de status para o endpoint e especifica o tipo de retorno do objeto (JSON/XML).

E o mais importante—não foi necessário escrever nenhum código adicional para gerar essa documentação!

Apenas adicionar a dependência e configurá-la se necessário (embora frequentemente nenhuma configuração seja exigida) já é suficiente para obter automaticamente a documentação da sua REST API!

Trabalhando com Anotações

Revisão breve das anotações abordadas neste capítulo:

@Tag – Agrupa endpoints relacionados e adiciona uma descrição a eles.

BookController.java


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

@Operation – Descreve um método de API específico, incluindo seu propósito e uma breve descrição.

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 – Descreve os parâmetros do método, como variáveis de caminho, parâmetros de consulta, entre outros.

BookController.java


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

@ApiResponse – Descreve uma única possível resposta específica, incluindo o código de resposta e sua descrição.

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 um conjunto de possíveis respostas para o método, incluindo códigos de status e descrições.

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);
}

Projeto

Também estou fornecendo um link para o projeto caso algo não esteja funcionando ou se você quiser explorá-lo em mais detalhes:

Resumo

Swagger permite a geração automática de documentação detalhada para sua API, tornando seu uso e teste mais fáceis.

Com anotações como @Operation, @ApiResponse e @Parameter, é possível descrever o comportamento de métodos, parâmetros e possíveis respostas sem adicionar código extra. Isso torna sua REST API mais clara e acessível para desenvolvedores.

Tudo estava claro?

Obrigado pelo seu feedback!

Seção 3. Capítulo 7

Pergunte à IA

Pergunte o que quiser ou experimente uma das perguntas sugeridas para iniciar nosso bate-papo

Suggested prompts:

Can you explain more about how to use Swagger annotations in my own project?

What are some best practices for writing clear API documentation with Swagger?

How do I handle custom error responses in Swagger documentation?

Awesome!

Completion rate improved to 3.45

Deslize para mostrar o menu

Introdução ao Swagger

No vídeo, você foi apresentado à interface principal do Swagger e como interagir com ela.

Para métodos que aceitam um corpo de requisição, o Swagger gera automaticamente o JSON com base no objeto que o endpoint atual recebe.

Além disso, se houver parâmetros na URL, é possível especificá-los facilmente nos campos correspondentes.

Swagger também exibe os possíveis códigos de status para o endpoint e especifica o tipo de retorno do objeto (JSON/XML).

E o mais importante—não foi necessário escrever nenhum código adicional para gerar essa documentação!

Trabalhando com Anotações

Revisão breve das anotações abordadas neste capítulo:

@Tag – Agrupa endpoints relacionados e adiciona uma descrição a eles.

BookController.java


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

@Operation – Descreve um método de API específico, incluindo seu propósito e uma breve descrição.

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 – Descreve os parâmetros do método, como variáveis de caminho, parâmetros de consulta, entre outros.

BookController.java


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

@ApiResponse – Descreve uma única possível resposta específica, incluindo o código de resposta e sua descrição.

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 um conjunto de possíveis respostas para o método, incluindo códigos de status e descrições.

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);
}

Projeto

Também estou fornecendo um link para o projeto caso algo não esteja funcionando ou se você quiser explorá-lo em mais detalhes:

Resumo

Swagger permite a geração automática de documentação detalhada para sua API, tornando seu uso e teste mais fáceis.

Tudo estava claro?

Obrigado pelo seu feedback!

Seção 3. Capítulo 7

Testando API RESTful

Introdução ao Swagger

Trabalhando com Anotações

Projeto

Resumo

Awesome!

Testando API RESTful

Introdução ao Swagger

Trabalhando com Anotações

Projeto

Resumo