Visão Geral
A documentação é uma parte essencial da construção de APIs REST. Neste tutorial, veremos SpringDoc, que simplifica a geração e manutenção de documentos de API com base na especificação OpenAPI 3 para aplicativos Spring Boot 3.x.
Configuração
Spring Boot 3.x requer o uso da versão 2 do springdoc-openapi:
ext { springdocVersion = "2.3.0" } dependencies { implementation "org.springframework.boot:spring-boot-starter-web" // ... implementation "org.springframework.boot:spring-boot-starter-validation" implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:${springdocVersion}" implementation "org.springdoc:springdoc-openapi-starter-common:${springdocVersion}" // ... testImplementation "org.springframework.boot:spring-boot-starter-test" } Depois de configurar a dependência corretamente, podemos executar nossa aplicação e encontrar as descrições da OpenAPI em /v3/api-docs, que é o caminho padrão:
http://localhost:8080/v3/api-docs Podemos personalizar o caminho em application.properties usando a propriedade springdoc.api-docs. Por exemplo, podemos definir o caminho para /api-docs:
springdoc.api-docs.path=/api-docs Então, poderemos acessar a documentação na url:
http://localhost:8080/api-docs As definições OpenAPI estão no formato JSON por padrão. Para o obter o formato yaml, podemos podemos acessar a url:
http://localhost:8080/api-docs.yaml Integração com UI Swagger
Além de gerar a especificação OpenAPI 3, podemos integrar springdoc-openapi com Swagger UI para interagir com nossa especificação de API e testar os endpoints. A dependência springdoc-openapi já inclui a UI do Swagger, então neste ponto, já podemos acessar a Swagger UI em:
http://localhost:8080/swagger-ui/index.html Support for swagger-ui Properties
A biblioteca springdoc-openapi também suporta propriedades swagger-ui. Elas podem ser usados como propriedades Spring Boot com o prefixo springdoc.swagger-ui. Por exemplo, podemos personalizar o caminho da Swagger UI alterando a propriedade springdoc.swagger-ui.path dentro do nosso arquivo application.properties:
springdoc.swagger-ui.path=/documentation.html Então podemos acessar a Swagger UI na url:
http://localhost:8080/documentation.html API de exemplo
import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import org.springframework.web.util.UriComponentsBuilder; import java.util.Collection; @RestController @RequestMapping("/api/books") public class BookController { private final BookRepository repository; public BookController(BookRepository repository) { this.repository = repository; } @PostMapping public ResponseEntity<?> create(@RequestBody final Book payload, UriComponentsBuilder ucb) { Book book = repository.create(payload); var location = ucb .path("/movies/{id}") .buildAndExpand(book.getId()) .toUri(); return ResponseEntity.created(location).build(); } @GetMapping("/{id}") public Book findById(@PathVariable final Long id) { return repository.findById(id) .orElseThrow(BookNotFoundException::new); } @GetMapping("/") public Collection<Book> findBooks() { return repository.getBooks(); } @PutMapping("/{id}") @ResponseStatus(HttpStatus.OK) public ResponseEntity<?> update(@PathVariable("id") final Long id, @RequestBody final Book payload) { if (repository.findById(id).isEmpty()) return ResponseEntity.notFound().build(); return ResponseEntity.accepted().body(repository.update(id, payload)); } @DeleteMapping("/{id}") public ResponseEntity<?> delete(@PathVariable final Long id) { Book book = repository.findById(id).orElseThrow(BookNotFoundException::new); repository.delete(book); return ResponseEntity.noContent().build(); } } Repositório de exemplo
import org.springframework.stereotype.Repository; import java.util.*; @Repository public class BookRepository { private final Map<Long, Book> books = new HashMap<>(); public Optional<Book> findById(final long id) { return Optional.ofNullable(books.get(id)); } public Book create(Book book) { Long id = (long) (books.size() + 1); book.setId(id); books.put(id, book); return books.get(id); } public Collection<Book> getBooks() { return books.values(); } public Book update(final long id, final Book book) { Book bookUpdate = books.get(id); bookUpdate.setAuthor(book.getAuthor()); bookUpdate.setTitle(book.getTitle()); books.put(id, bookUpdate); return books.get(id); } public void delete(final Book book) { books.remove(book.getId()); } } Modelo de exemplo
import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.Size; public class Book { private long id; private String title; private String author; // Getters and Setters } class BookNotFoundException extends RuntimeException { } Application Properties de exemplo
# Open Api springdoc.api-docs.path=/api-docs springdoc.swagger-ui.operationsSorter=alpha springdoc.api-docs.version=OPENAPI_3_0 spring.jpa.hibernate.ddl-auto=none # Swagger springdoc.swagger-ui.path=/documentation.html Testando
Então, se executarmos nossa API agora, podemos visualizar a documentação em:
http://localhost:8080/documentation.html 
Aqui podemos usar a Swagger UI para testar nossa API fazendo:
- cadastro de novos livros
- obtendo todos os livros cadastrados
- obtendo um livro pelo id
- atualizando um livro cadastrado
- deletando um livro cadastrado
Faça testes e explore a Documentação gerada automáticamente.
Geração automática de documentos usando validação de bean JSR-303
Quando nosso modelo inclui anotações de validação de bean JSR-303, como @NotNull, @NotBlank, @Size, @Min e @Max, a biblioteca springdoc-openapi utiliza essas anotações para gerar documentação de esquema adicional para as restrições correspondentes. Vejamos um exemplo usando nosso bean Book:
public class Book { private long id; @NotBlank @Size(min = 0, max = 20) private String title; @NotBlank @Size(min = 0, max = 30) private String author; } Percebe agora como ficou a documentação do Schema de Book:
Gerando documentação adicional usando @ControllerAdvice e @ResponseStatus:
Usar @ResponseStatus em métodos em uma classe @RestControllerAdvice o openapi vai gerar automaticamente documentação para os códigos de resposta. Nesta classe @RestControllerAdvice, os dois métodos são anotados com @ResponseStatus:
import org.springframework.core.convert.ConversionFailedException; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.ResponseStatus; import org.springframework.web.bind.annotation.RestControllerAdvice; @RestControllerAdvice public class GlobalControllerExceptionHandler { @ExceptionHandler(ConversionFailedException.class) @ResponseStatus(HttpStatus.BAD_REQUEST) public ResponseEntity<String> handleConversion(RuntimeException ex) { return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST); } @ExceptionHandler(BookNotFoundException.class) @ResponseStatus(HttpStatus.NOT_FOUND) public ResponseEntity<String> handleBookNotFound(RuntimeException ex) { return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND); } } As a result, we can now see the documentation for the response codes 400 and 404:
Gerando documentação usando @Operation e @ApiResponses
A seguir, vamos ver como podemos adicionar alguma descrição à nossa API usando algumas anotações da especificação OpenAPI.
Para fazer isso, anotaremos o endpoint /api/book/{id} do nosso controlador com @Operation e @ApiResponses:
@Operation(summary = "Get a book by its id") @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "Found the book", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Book.class)) }), @ApiResponse(responseCode = "400", description = "Invalid id supplied", content = @Content), @ApiResponse(responseCode = "404", description = "Book not found", content = @Content) }) @GetMapping("/{id}") public Book findById(@Parameter(description = "id of book to be searched") @PathVariable long id) { return repository.findById(id).orElseThrow(() -> new BookNotFoundException()); } Agora nosso endpoint /api/book/{id} ficou documentado assim:
Conclusão
Neste artigo, aprendemos como configurar o springdoc-openapi em nossos projetos. Em seguida, vimos como integrar springdoc-openapi com a UI do Swagger.
Depois disso, vimos como o springdoc-openapi gera documentação automaticamente usando anotações de validação de bean JSR 303 e as anotações @ResponseStatus na classe @ControllerAdvice.
Também aprendemos como adicionar uma descrição à nossa API usando algumas anotações específicas da OpenAPI
O springdoc-openapi gera documentação da API de acordo com as especificações do OpenAPI 3. Além disso, ele também cuida da configuração da UI do Swagger para nós, tornando a geração de documentos da API uma tarefa razoavelmente simples.
Top comments (0)