Geração Swagger/OpenAPI para Java: melhores bibliotecas

Geração Swagger/OpenAPI para Java: guia completo de ferramentas

No desenvolvimento moderno em Java, criar documentação de API de qualidade tornou-se uma parte essencial do processo. A especificação OpenAPI (anteriormente conhecida como Swagger) fornece um formato padronizado para descrever APIs RESTful. Neste artigo, vamos explorar as principais ferramentas para geração de documentação Swagger/OpenAPI em projetos Java, suas características e exemplos de uso.

O que são Swagger e OpenAPI?

Swagger é um conjunto de ferramentas para projetar, criar e documentar APIs REST. OpenAPI é uma especificação que define o padrão de descrição de API. Swagger é a implementação mais popular desta especificação.

Principais bibliotecas para Java

Vamos analisar três ferramentas-chave:

• SpringDoc OpenAPI — biblioteca moderna para Spring Boot
• Swagger Core — biblioteca base dos criadores do Swagger
• OpenAPI Generator — ferramenta para geração de código e documentação

1. SpringDoc OpenAPI

SpringDoc é a escolha mais popular para projetos em Spring Boot. Ele se integra automaticamente à sua aplicação e gera documentação com base em anotações e tipos de dados.

Instalação e configuração

Adicione a dependência no pom.xml:

<dependency>    <groupId>org.springdoc</groupId>    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>    <version>2.6.0</version></dependency>

Exemplo de uso

Crie um controlador simples com documentação:

@RestController@RequestMapping("/api/users")@Tag(name = "Usuários", description = "Gerenciamento de usuários")public class UserController {

    @GetMapping("/{id}")    @Operation(summary = "Obter usuário por ID")    public ResponseEntity<User> getUser(            @Parameter(description = "ID do usuário")            @PathVariable Long id) {        // implementação        return ResponseEntity.ok(new User(id, "João"));    }

    @PostMapping    @Operation(summary = "Criar novo usuário")    public ResponseEntity<User> createUser(            @RequestBody @Valid CreateUserRequest request) {        // implementação        return ResponseEntity.status(201).body(new User(1L, request.getName()));    }}

Após iniciar a aplicação, a documentação estará disponível em http://localhost:8080/swagger-ui.html.

2. Swagger Core

A biblioteca Swagger Core oferece uma abordagem de nível mais baixo para criar a especificação OpenAPI. É adequada para projetos onde é necessário controle total sobre a geração.

Exemplo de criação manual da especificação

import io.swagger.v3.oas.models.*;import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("Pet Store API")        .description("API para gerenciamento de animais de estimação")        .version("1.0.0")        .contact(new Contact()            .name("Desenvolvedor")            .email("dev@example.com")))    .addServersItem(new Server()        .url("https://api.example.com/v1")        .description("Servidor de produção"));

// Adicionando caminhos e componentesPaths paths = new Paths();paths.addPathItem("/pets", new PathItem()    .get(new Operation()        .operationId("listPets")        .summary("Obter lista de animais de estimação")));openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator é uma ferramenta que pode gerar tanto documentação quanto código cliente/servidor com base na especificação OpenAPI.

Uso no Maven

Adicione o plugin no pom.