OpenAPI / Swagger Java: métodos, exemplos, instalação |…

O que é OpenAPI / Swagger e por que um desenvolvedor Java precisa disso?

\n\n

OpenAPI (anteriormente conhecido como Swagger) é uma especificação para descrever, criar, documentar e consumir APIs RESTful. Para o desenvolvedor Java, as bibliotecas OpenAPI / Swagger são uma ferramenta indispensável que automatiza o processo de documentação de API e geração de código cliente.

\n\n

Principais razões para usar OpenAPI / Swagger em projetos Java:

Geração automática de documentação — a biblioteca analisa seu código (anotações Spring Boot, JAX-RS) e cria documentação interativa no formato Swagger UI.
Padronização — formato único de descrição de API, compreensível tanto para humanos quanto para máquinas.
Geração de código cliente — é possível gerar um cliente Java para qualquer API descrita em OpenAPI.
Testes — Swagger UI permite executar requisições para a API diretamente do navegador.
Integração com CI/CD — é possível verificar a conformidade da API com a especificação na etapa de build.

\n\n

Neste artigo, abordaremos duas principais bibliotecas Java: springdoc-openapi (para Spring Boot) e Swagger Core (para JAX-RS e outros frameworks).

\n\n

Instalação da biblioteca OpenAPI / Swagger para Java

\n\n

A instalação depende do framework utilizado. Vamos considerar duas opções principais.

\n\n

Opção 1: Spring Boot (springdoc-openapi)

Adicione a dependência ao seu pom.xml (Maven):

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

\n\n

Para Gradle (build.gradle):

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

\n\n

Opção 2: JAX-RS / Jakarta (Swagger Core)

Maven:

<dependency>\n    <groupId>io.swagger.core.v3</groupId>\n    <artifactId>swagger-jaxrs2-jakarta</artifactId>\n    <version>2.2.22</version>\n</dependency>

\n\n

Gradle:

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

\n\n

Início rápido: primeiro exemplo com Spring Boot

\n\n

Após adicionar a dependência springdoc-openapi em um projeto Spring Boot, o Swagger UI fica automaticamente disponível em http://localhost:8080/swagger-ui.html. Vamos criar um controlador simples:

\n\n

import io.swagger.v3.oas.annotations.Operation;\nimport io.swagger.v3.oas.annotations.tags.Tag;\nimport org.springframework.web.bind.annotation.*;\n\n@RestController\n@RequestMapping("/api/users")\n@Tag(name = "User Controller", description = "Gerenciamento de usuários")\npublic class UserController {\n\n    @GetMapping("/{id}")\n    @Operation(summary = "Obter usuário por ID")\n    public String getUser(@PathVariable Long id) {\n        return "User with ID: " + id;\n    }\n\n    @PostMapping\n    @Operation(summary = "Criar novo usuário")\n    public String createUser(@RequestBody String userName) {\n        return "Created user: " + userName;\n    }\n}

\n\n

Após iniciar a aplicação, abra http://localhost:8080/swagger-ui.html — você verá a documentação interativa com a possibilidade de executar requisições.

\n\n