Aula 12 - Documentação de API com Swagger 📝

Uma API sem documentação é um labirinto no escuro. Nesta aula, vamos documentar automaticamente nossa API usando Swagger/OpenAPI.

😊 Por que Documentar APIs?

Developer Experience (DX): facilita o consumo da API por outros times e sistemas.
Single Source of Truth: o contrato documentado é a verdade absoluta do sistema.
Testabilidade: o Swagger UI permite testar endpoints direto do navegador, sem precisar do Postman.

🧠 Integrando o Swagger ao Spring Boot

Adicionando a dependência springdoc-openapi ao projeto, o Spring já gera automaticamente a documentação a partir dos seus Controllers, sem esforço manual.

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

📊 Como Funciona

graph LR
    A[Controllers com anotações Spring] --> B[springdoc-openapi]
    B --> C[Especificação OpenAPI - JSON]
    C --> D[Swagger UI - Página interativa]

🧠 Enriquecendo a Documentação

Important

Anotações como @Operation e @Schema permitem adicionar descrições legíveis por humanos, além do que o Spring já infere automaticamente.

@Operation(summary = "Lista todos os produtos cadastrados")
@GetMapping
public List<ProdutoDTO> listar() {
    return service.listarTodos();
}

💻 Acessando a Documentação

$ ./mvnw spring-boot:run
$ # Acesse no navegador:
$ # http://localhost:8080/swagger-ui.html

Tip

O Swagger UI permite testar endpoints diretamente na página — inclusive endpoints protegidos (Aula 13), informando o token JWT.

📝 Exercícios Progressivos

Básico: O que é o Swagger UI e para que ele serve?
Básico: Qual a vantagem de gerar documentação automaticamente em vez de escrevê-la manualmente?
Intermediário: O que faz a anotação @Operation?
Intermediário: Como o Swagger UI pode ser usado em vez do Postman durante o desenvolvimento?
Desafio: Adicione descrições @Operation a todos os endpoints do ProdutoController.

🚀 Mini-projeto: Adicione o springdoc-openapi ao projeto e acesse a documentação interativa gerada automaticamente para o ProdutoController.