Documentando uma API REST Spring usando o OpenAPI 3.0

1. Visão geral

A documentação é uma parte essencial da construção de APIs REST. Neste tutorial, daremos uma olhada no SpringDoc - uma ferramenta que simplifica a geração e manutenção de documentos da API, com base na especificação OpenAPI 3, para aplicativos Spring Boot 1.xe 2.x.

2. Configurando springdoc-openapi

Para quespringdoc-openapi gere automaticamente os documentos de especificação OpenAPI 3 para nossa API, simplesmente adicionamos a dependênciaspringdoc-openapi-core ao nossopom.xml:


    org.springdoc
    springdoc-openapi-core
    1.1.44

Então, quando executarmos nosso aplicativo, os documentos estarão disponíveis no caminho/v3/api-docs por padrão - por exemplo:

http://localhost:8080/v3/api-docs/

Para usar um caminho personalizado, podemos indicar no arquivoapplication.properties:

springdoc.api-docs.path=/api-docs

Agora, podemos acessar os documentos em:

http://localhost:8080/api-docs/

As definições de OpenAPI estão no formato JSON_ format by default. For _yaml, podemos obter as definições em:

http://localhost:8080/api-docs.yaml

3. Configurando springdoc-openapi com Swagger UI

Além de gerar a própria especificação OpenAPI 3, podemos integrar o springdoc-openapi à interface do usuário do Swagger, para que possamos interagir com a especificação da API e exercitar os pontos de extremidade.

3.1. Dependência do Maven

Tudo o que precisamos fazer para configurar springdoc-openapi com Swagger UI é adicionar a dependênciaspringdoc-openapi-ui aopom.xml do projeto:


    org.springdoc
    springdoc-openapi-ui
    1.1.44

Agora podemos acessar a documentação da API em:

http://localhost:8080/swagger-ui.html

Podemos personalizar o caminho adicionando a propriedade:

springdoc.swagger-ui.path=/swagger-ui-custom.html

3.2. API de amostra

Suponha que nosso aplicativo tenha um controlador para gerenciarBooks:

@RestController
@RequestMapping("/api/book")
public class BookController {

    @Autowired
    private BookRepository repository;

    @GetMapping("/{id}")
    public Book findById(@PathVariable long id) {
        return repository.findById(id)
            .orElseThrow(() -> new BookNotFoundException());
    }

    @GetMapping("/")
    public Collection findBooks() {
        return repository.getBooks();
    }

    @PutMapping("/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Book updateBook(@PathVariable("id") final String id, @RequestBody final Book book) {
        return book;
    }
}

Então, quando executamos nosso aplicativo, podemos visualizar a documentação em:

http://localhost:8080/swagger-ui-custom.html

Vamos detalhar até o endpoint/api/book e ver os detalhes de sua solicitação e resposta:

4. Integrando springdoc-openapi com Spring WebFlux

Podemos integrar springdoc-openapi e Swagger UI em um projeto Spring WebFlux adicionandospringdoc-openapi-webflux-ui:


    org.springdoc
    springdoc-openapi-webflux-ui
    1.1.44

E, como antes, os documentos estarão acessíveis em:

http://localhost:8080/swagger-ui.html

Aqui, novamente, podemos adicionar a propriedadespringdoc.swagger-ui.path no arquivoapplication.properties para personalizar o caminho.

5. Usando o plugin springdoc-openapi Maven

A biblioteca springdoc-openapi fornece um plugin Mavenspringdoc-openapi-maven-plugin para gerar descrições OpenAPI nos formatosjsoneyaml.

O pluginspringdoc-openapi-maven-plugin funciona com o pluginspring-boot-maven. O Maven executa o pluginopenapi durante a faseintegration-test.

Vamos ver como podemos configurar o plugin em nossopom.xml:


    org.springframework.boot
    spring-boot-maven-plugin
    2.1.8.RELEASE
    
        
            pre-integration-test
            
                start
            
        
        
            post-integration-test
            
                stop
            
        
    


    org.springdoc
    springdoc-openapi-maven-plugin
    0.2
    
        
            integration-test
            
                generate

Além disso, podemos configurar o plug-in para usar valores personalizados:


    
        .........
    
    
        http://localhost:8080/v3/api-docs
        openapi.json
        ${project.build.directory}

Vamos dar uma olhada mais de perto nos parâmetros que podemos configurar para o plugin:

apiDocsUrl - URL onde os documentos podem ser acessados no formatojson, com um padrão dehttp://localhost:8080/v3/api-docs
outputFileName - Nome do arquivo onde as definições são armazenadas, o padrão éopenapi.json
outputDir - caminho absoluto para o diretório onde os documentos são armazenados - por padrão,$\{project.build.directory}

6. Geração automática de documentos usando validação JSR-303 Bean

Quando nosso modelo inclui anotações de validação de bean JSR-303, como@NotNull,@NotBlank,@Size,@Min e@Max, a biblioteca springdoc-openapi usa para gerar documentação de esquema adicional para as restrições correspondentes.

Vejamos um exemplo usando nosso beanBook:

public class Book {

    private long id;

    @NotBlank
    @Size(min = 0, max = 20)
    private String title;

    @NotBlank
    @Size(min = 0, max = 30)
    private String author;

}

Agora, a documentação gerada para o beanBook é um pouco mais informativa:

7. Gerar documentação usando@ControllerAdvice e@ResponseStatus

Usar@ResponseStatus em métodos em uma classe@RestControllerAdvice gerará automaticamente a documentação para os códigos de resposta. Nesta classe@RestControllerAdvice, os dois métodos são anotados com@ResponseStatus:

@RestControllerAdvice
public class GlobalControllerExceptionHandler {

    @ExceptionHandler(ConversionFailedException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity handleConnversion(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(BookNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity handleBookNotFound(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

E agora veremos a documentação dos códigos de resposta 400 e 404:

8. Conclusão

Neste artigo, aprendemos a configurar o springdoc-openapi em nossos projetos. Em seguida, vimos como integrar o springdoc-openapi à interface do usuário do Swagger. Também vimos como fazer isso nos projetos Spring Webflux.

Em seguida, usamos o plug-in Maven springdoc-openapi para gerar definições de OpenAPI para nossas APIs. Finalmente, vimos como springdoc-openapi gera documentação automaticamente usando as anotações de validação do bean JSR 303 e as anotações@ResponseStatus na classe@ControllerAdvice.

O springdoc-openapi gera documentação da API conforme a especificação do OpenAPI 3. Ele lida com a configuração da interface do usuário do Swagger para nós, tornando a geração de documentos da API uma tarefa bastante simples.

Como sempre, o código está disponívelover on GitHub.

TOC

Documentando uma API REST Spring usando o OpenAPI 3.0