Geração Swagger/OpenAPI para Java: visão geral das…

Geração Swagger/OpenAPI para Java: visão geral completa de ferramentas e bibliotecas

O desenvolvimento moderno de REST API em Java é impensável sem documentação de qualidade. O padrão OpenAPI (anteriormente conhecido como Swagger Specification) tornou-se o padrão industrial de facto para descrever HTTP APIs. Neste artigo, analisaremos detalhadamente as principais bibliotecas e ferramentas para geração de especificações OpenAPI em aplicações Java, suas capacidades, exemplos de uso e critérios de escolha.

O que é OpenAPI e para que serve?

OpenAPI é uma especificação que descreve uma API RESTful no formato JSON ou YAML. Ela inclui:

lista de endpoints e métodos HTTP;
modelos de dados (esquemas de requisições e respostas);
parâmetros (query, path, header);
informações sobre autenticação e autorização.

A documentação gerada a partir do OpenAPI permite criar automaticamente SDKs cliente, realizar testes e manter a descrição da API atualizada. Para Java, existem várias soluções maduras.

1. SpringDoc OpenAPI (recomendado para Spring Boot)

SpringDoc é a biblioteca mais popular para geração de OpenAPI 3 no ecossistema Spring. Ela escaneia automaticamente os controladores, anotações @RequestMapping, @GetMapping, etc., e constrói a especificação com base neles.

Adição (Maven)

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

Exemplo de controlador com anotações

@RestController@RequestMapping("/api/users")public class UserController {

    @Operation(summary = "Obter usuário por ID")    @ApiResponses(value = {        @ApiResponse(responseCode = "200", description = "Usuário encontrado"),        @ApiResponse(responseCode = "404", description = "Usuário não encontrado")    })    @GetMapping("/{id}")    public ResponseEntity<User> getUser(@PathVariable Long id) {        // lógica        return ResponseEntity.ok(new User(id, "Ivan", "ivan@example.com"));    }}

Após iniciar a aplicação, a documentação está disponível em /swagger-ui.html, e a especificação em JSON em /v3/api-docs.

2. Swagger Core (OpenAPI 3.0)

Swagger Core é uma biblioteca de baixo nível dos criadores da especificação. Ela permite construir objetos OpenAPI programaticamente e serializá-los em JSON/YAML. É adequada para casos onde é necessário um controle refinado da geração.

Exemplo de criação programática de especificação

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

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("Exemplo de API")        .version("1.0.0")        .description("Documentação criada manualmente"))    .path("/hello", new PathItem()        .get(new Operation()            .summary("Saudação")            .operationId("sayHello")            .addParametersItem(new Parameter()                .name("name")                .in("query")                .required(false)                .schema(new StringSchema()))            .responses(new ApiResponses()                .addApiResponse("200", new ApiResponse()                    .description("OK")                    .content(new Content()                        .addMediaType("text/plain",                             new MediaType().schema(new StringSchema())))))));

// Serialização em JSONObjectMapper mapper = new ObjectMapper();String json = mapper.writeValueAsString(openAPI);System.out.println(json);