Encontro 02 - Configurar Swagger/OpenAPI para documentar automaticamente os endpoints.

Configurar SwaggerOpenAPI para documentar automaticamente os endpoints.md

Atividade 3: Configurar Swagger/OpenAPI para documentar automaticamente os endpoints

1. O que é o Swagger/OpenAPI?

Definição: Swagger (agora conhecido como OpenAPI) é uma especificação para documentação de APIs RESTful. Objetivo: Permitir que desenvolvedores documentem suas APIs de forma padronizada e automatizada.

Componentes principais:

• Swagger UI: Interface visual interativa para explorar e testar APIs
• OpenAPI Specification: O padrão formal que define a estrutura da documentação

2. Por que usar Swagger em projetos Spring Boot?

• Documentação automática: Gera documentação detalhada dos endpoints sem escrever documentação manual.

• Interface interativa: Permite testar chamadas à API diretamente do navegador.

• Facilita testes e depuração: Oferece uma maneira rápida de verificar requisições e respostas.

• Melhora a comunicação: Ajuda outros desenvolvedores a entenderem sua API.

• Adoção de padrões de mercado: OpenAPI é um padrão amplamente adotado na indústria.

3. Implementação no Spring Boot (passo a passo)

Objetivo

Implementar o Swagger/OpenAPI na aplicação delivery-tech para documentar automaticamente os endpoints /health e /info.

Instruções

1. Adicione as dependências necessárias ao arquivo pom.xml:

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

2. Configure as propriedades básicas do Swagger no arquivo application.properties:

O arquivo application.properties é um arquivo de configuração fundamental em aplicações Spring Boot. Ele permite definir diversas propriedades que controlam o comportamento da aplicação, sem necessidade de alterar código-fonte.

Por que usar o application.properties?

1. Configuração externalizável: Permite modificar comportamentos da aplicação sem recompilar código
2. Perfis de ambiente: Facilita configurações específicas para ambientes (dev, test, prod)
3. Definição de portas, URLs e credenciais: Centraliza configurações importantes
4. Personalização de logs: Permite configurar nível de logs e formatos
5. Configurações específicas: Permite ajustar comportamentos de segurança, banco de dados, etc.

Estrutura do Projeto:

src/
  main/
    resources/
      application.properties.java  <-- Implementação aqui

script:

# ===== CONFIGURAÇÃO H2 DATABASE =====
spring.datasource.url=jdbc:h2:mem:delivery
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# ===== H2 CONSOLE =====
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console
spring.h2.console.settings.web-allow-others=true

# JPA/Hibernate
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# Configuracoes de desenvolvimento
spring.devtools.restart.enabled=true

# Configuracoes especificas para JDK 21
spring.jpa.open-in-view=false
logging.level.org.springframework.web=DEBUG
logging.level.org.springframework.jdbc.datasource.init=DEBUG

# Executar scripts SQL automaticamente
# spring.sql.init.mode=always
# spring.sql.init.data-locations=classpath:data.sql
# spring.sql.init.schema-locations=classpath:schema.sql

# Configuracao customizada do swagger
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha

# JWT Configuration
jwt.secret=my-secret-keyQWERTYUIOPASDFGHJKLZXCVBNMQWERTY1
jwt.expiration=86400000

# Security Configuration - APENAS UMA CONFIGURAÇÃO
spring.security.user.name=admin
spring.security.user.password=admin

# Logging
logging.level.org.springframework.security=DEBUG
logging.level.com.deliverytech=DEBUG
logging.level.web=DEBUG
logging.level.io.micrometer=DEBUG
logging.level.root=INFO
 
# Configurações do Actuator e Métricas
management.endpoints.web.exposure.include=health,info,prometheus,metrics
management.endpoint.health.show-details=always
management.prometheus.metrics.export.enabled=true
management.endpoint.info.enabled=true
management.info.env.enabled=true
management.info.java.enabled=true
management.metrics.web.server.request.autotime.enabled=false
management.metrics.web.server.request.timed.enabled=true
management.endpoint.prometheus.enabled=true
management.prometheus.metrics.export.enabled=true
management.info.git.enabled=true
management.info.git.mode=full

# Informações da Aplicação (para /actuator/info)
info.app.name=DeliveryTech API
info.app.description=API de entrega com monitoramento
info.app.version=1.0.0
info.custom.feature-status=Paginação, Cache e Health Checks habilitados
info.custom.last-deployment-date=2025-07-23
info.custom.contact-email=suporte@deliverytech.com

3. Crie uma classe de configuração do OpenApiConfig

Estrutura do Projeto:

src/
  main/
    java/
      com/
        deliverytech/
          delivery_api/
            config/
              OpenApiConfig.java  <-- Implementação aqui

script:

package com.deliverytech.delivery_api.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Delivery Tech API")
                        .version("1.0.0")
                        .description("API para sistema de delivery")
                        .contact(new Contact()
                                .name("Seu Nome")
                                .email("seu.email@exemplo.com")));
    }
}

4. Adicione anotações do OpenAPI no controlador HealthController:

O que são endpoints de saúde (health) e informação (info)?

Health Check (Verificação de Saúde)

Um endpoint /health é um ponto de acesso na API que permite verificar se a aplicação está funcionando corretamente. Este endpoint é essencial em aplicações modernas, especialmente em arquiteturas de microserviços.

Funcionalidades principais:

• Informa se a aplicação está online e respondendo a requisições
• Pode verificar dependências críticas (banco de dados, serviços externos, etc.)
• Permite monitoramento automático e alertas
• Auxilia em estratégias de balanceamento de carga e failover

Info (Informações)

Um endpoint /info fornece metadados e informações sobre a aplicação em execução. Estas informações são valiosas para equipes de desenvolvimento, operações e suporte.

Funcionalidades principais:

• Exibe versão da aplicação
• Mostra informações sobre o ambiente
• Lista dependências e suas versões
• Fornece informações sobre o ambiente de execução
• Pode incluir detalhes de configuração (não-sensíveis)

Por que implementar esses endpoints no projeto Delivery Tech?

1. Monitoramento e Observabilidade:

   • Permitem verificar facilmente se o sistema está online
   • Facilitam a integração com ferramentas de monitoramento

2. DevOps e Operações:

   • Ajudam na automatização de implantações
   • Permitem verificações de saúde em pipelines CI/CD

3. Diagnóstico e Suporte:

   • Fornecem informações rápidas para troubleshooting
   • Ajudam a identificar versões em execução

4. Boas Práticas de Desenvolvimento:

   • Seguem padrões da indústria para aplicações robustas
   • Facilitam a manutenção da aplicação

Estrutura do Projeto:

src/
  main/
    java/
      com/
        deliverytech/
          delivery_api/
            controller/
              HealthController.java  <-- Implementação aqui

script:

package com.deliverytech.delivery_api.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDateTime;
import java.util.Map;

@RestController
@Tag(name = "Health", description = "Endpoints para verificação de integridade do sistema")
public class HealthController {

    @Operation(
        summary = "Verificar status da aplicação",
        description = "Retorna o status atual da aplicação e timestamp"
    )
    @GetMapping("/health")
    public Map<String, String> health() {
        return Map.of(
            "status", "UP",
            "timestamp", LocalDateTime.now().toString(),
            "service", "Delivery API",
            "javaVersion", System.getProperty("java.version")
        );
    }

    @Operation(
        summary = "Informações da aplicação",
        description = "Retorna detalhes sobre a versão e configuração da aplicação"
    )
    @GetMapping("/info")
    public AppInfo info() {
        return new AppInfo(
            "Delivery Tech API",
            "1.0.0",
            "Seu Nome",
            "JDK 21",
            "Spring Boot 3.5.x"
        );
    }

    public record AppInfo(
        String application,
        String version,
        String developer,
        String javaVersion,
        String framework
    ) {}
}

5. Execute a aplicação usando o método main em DeliveryApiApplication ou com o comando Maven:

   ./mvnw spring-boot:run
   

6. Acesse a documentação Swagger em seu navegador:

   • Interface do Swagger UI: http://localhost:8080/swagger-ui.html
   • Documentação OpenAPI em JSON: http://localhost:8080/api-docs

7. Explore a documentação gerada:

   • Verifique se os endpoints /health e /info estão listados corretamente
   • Teste os endpoints diretamente pela interface do Swagger
   • Observe as descrições e detalhes dos endpoints que você documentou