Documentando API's com Springdoc OpenAPI

No mundo do desenvolvimento de software, especialmente no contexto de APIs REST, uma documentação clara e precisa é essencial para garantir a compreensão e a usabilidade das interfaces. No ecossistema Java, a combinação de Spring Docs e Bean Validation oferece uma abordagem robusta e eficaz para construir APIs bem documentadas e com validações automáticas. Neste artigo, vamos explorar as vantagens dessa implementação e como ela pode melhorar a qualidade do seu projeto.

Documentação de APIs REST com Spring Docs

A documentação de uma API é crucial para a interação com outros sistemas e desenvolvedores. Sem uma documentação adequada, pode-se gerar confusão, erros e falta de compreensão sobre o funcionamento da API. O Spring Docs facilita esse processo, especialmente quando se utiliza o Spring Boot para construir suas APIs REST.

O Spring Docs é frequentemente integrado com o Swagger, uma ferramenta amplamente utilizada para gerar documentação interativa de APIs. A vantagem principal de usar o Spring Docs é a facilidade de configuração e a capacidade de gerar documentação automaticamente a partir do código. Utilizando anotações como @Api, @ApiOperation, @ApiResponse, entre outras, é possível fornecer uma descrição detalhada das rotas, parâmetros, tipos de resposta e erros que a API pode gerar.

Por exemplo, ao anotar um endpoint da seguinte maneira:

@Tag(name = "categorias", description = "API para ações no recurso Categoria")
@RestController
@RequestMapping("categorias")
public class CategoriaController {

    private final CategoriaService service;

    public CategoriaController(final CategoriaService c) {
        this.service = c;
    }

    @Operation(summary = "Cria uma nova Categoria", description = "Cria uma nova Categoria, caso ela não exista", tags = "categorias")
    @ApiResponses(value = { 
            @ApiResponse(
                    description = "Ação realizada com sucesso", responseCode = "201",
                    content = { @Content(mediaType = "application/json", 
                    schema = @Schema(implementation = CategoriaDTO.class)) }),
            @ApiResponse(
                    description = "Categoria exitente", responseCode = "409",
                    content = { @Content(mediaType = "application/json", 
                    schema = @Schema(implementation = Erro.class)) }),
            @ApiResponse(
                    description = "Ocorreu um erro interno inesperado na API", responseCode = "500",
                    content = { @Content(mediaType = "application/json", 
                    schema = @Schema(implementation = Erro.class)) }) 
            }
    )
    @PostMapping(value = "/", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseStatus(HttpStatus.CREATED)
    public CategoriaDTO create(
            @Valid @RequestBody @NotBlank(message = "O nome da nova Categoria não pode ser vazio!") String novaCategoria) {
        var dto = service.create(novaCategoria);
        return dto;
    }
}

O Spring Docs, juntamente com o Swagger, gera automaticamente a documentação interativa da API, permitindo que os desenvolvedores testem a API diretamente pela interface. Isso aumenta a produtividade da equipe e reduz a margem de erro, já que a documentação está sempre em sincronia com o código.
Para acessar a documentação gerada, acesse: http://localhost:8080/swagger-ui/index.html

Validação de Campos com Bean Validation

A validação de dados de entrada é outra prática essencial em APIs RESTful. No Spring, o Bean Validation é uma das ferramentas mais poderosas para garantir que os dados recebidos nos endpoints atendam aos critérios definidos. Isso não só melhora a confiabilidade da aplicação, como também evita a necessidade de escrever validações manuais e repetitivas.

O Bean Validation utiliza anotações como @NotNull, @Size, @Email, @min, entre outras, que podem ser aplicadas diretamente nas entidades ou nos parâmetros dos métodos. A validação é feita automaticamente pelo Spring antes de os dados serem processados, e caso algum dado inválido seja enviado, o Spring lança uma exceção de erro com uma mensagem clara sobre o que está errado.

Exemplo de validação utilizando Bean Validation:

@Getter
@Setter
public class ProdutoRequest implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotBlank(message = "O nome do produto é obrigatório!")
    private String nome;

    @NotBlank(message = "Uma descrição para o produto é obrigatório!")
    private String descricao;

    @Positive(message = "Um preço para o produto é obrigatório!")
    private BigDecimal preco;

    @NotNull(message = "Um ID de uma categoria deve se informado!")
    private Long categoriaId;

}

Ao utilizar essas anotações, o Spring Boot automaticamente valida os dados e, se houver algum erro, retorna uma resposta 400 (Bad Request) com uma mensagem detalhada sobre qual campo falhou na validação. Isso reduz a carga de trabalho do desenvolvedor e evita que erros de dados inválidos cheguem à camada de serviço ou banco de dados.

Vantagens da Implementação

1. Melhoria na Manutenção e Produtividade: A documentação automática reduz o tempo gasto criando e mantendo documentações desatualizadas, pois ela é gerada diretamente a partir do código-fonte. As anotações utilizadas no Spring Docs ficam sempre sincronizadas com os endpoints, facilitando futuras modificações e atualizações na API.

2. Consistência e Confiabilidade: A validação automática com Bean Validation garante que todos os dados recebidos sejam consistentes e atendam aos requisitos de integridade definidos. Isso minimiza erros humanos e aumenta a confiabilidade da API.

3. Facilidade de Uso para Consumidores da API: A documentação interativa do Swagger proporciona um ambiente onde outros desenvolvedores ou sistemas podem testar a API diretamente, sem necessidade de configurar um cliente separado. Isso acelera a integração e melhora a experiência do consumidor da API.

4. Escalabilidade: Ao combinar validação automática com uma documentação gerada de forma inteligente, o desenvolvedor pode escalar a API de forma mais segura e eficiente, pois as mudanças na API refletem diretamente na documentação e nas validações sem exigir trabalho adicional manual.

5. Redução de Erros e Melhor Debugging: Quando a validação de dados falha, a API retorna respostas claras e úteis, facilitando a identificação e correção de erros. Isso acelera o ciclo de desenvolvimento e torna mais fácil para os desenvolvedores depurarem a aplicação.

Conclusão

Integrar Spring Docs com Bean Validation em uma API REST é uma prática altamente recomendada para garantir que as APIs sejam bem documentadas e, ao mesmo tempo, seguras. A documentação automática melhora a interação entre desenvolvedores e sistemas, enquanto a validação de campos oferece maior confiança na integridade dos dados. Essa combinação de ferramentas do Spring resulta em uma arquitetura de API mais robusta, escalável e de fácil manutenção. Ao adotar essas práticas, você garante que sua API seja não só eficiente, mas também de fácil uso e integração para outros desenvolvedores.

Referências

Documentação do Springdocs
Documentação do Bean Validation
Fontes com o exemplo de implementação