Package org.praxisplatform.uischema.configuration

Class PraxisMetadataAutoConfiguration

java.lang.Object
org.praxisplatform.uischema.configuration.PraxisMetadataAutoConfiguration
@AutoConfiguration @ComponentScan(basePackages={"org.praxisplatform.uischema.controller.docs","org.praxisplatform.uischema.rest.exceptionhandler","org.praxisplatform.uischema.service","org.praxisplatform.uischema.filter","org.praxisplatform.uischema.configuration"}) public class PraxisMetadataAutoConfiguration extends Object

⚙️ Auto-Configuração Principal do Praxis Metadata Starter

Esta classe é responsável por configurar os aspectos estruturais e de integração do sistema Praxis Metadata, incluindo escaneamento de componentes, customizações OpenAPI e grupos de documentação de infraestrutura.

🎯 Objetivos Principais

  1. Component Scanning: Detecta e registra automaticamente todos os componentes do framework
  2. OpenAPI Integration: Configura customizações específicas para melhor documentação
  3. Infrastructure Groups: Cria grupos básicos de documentação para infraestrutura
  4. Type Mapping: Configura mapeamento correto de tipos Java para schemas OpenAPI

🔄 Diferença das Outras Auto-Configurações

ConfiguraçãoResponsabilidadeFoco
PraxisMetadataAutoConfiguration Estrutura base + Component Scan 🏗️ Infraestrutura
OpenApiUiSchemaAutoConfiguration Beans específicos do UI Schema 🎨 Funcionalidade
DynamicSwaggerConfig Grupos dinâmicos + Validação 🤖 Automação

📦 Component Scanning Strategy

Esta classe usa @ComponentScan para detectar automaticamente:

  • org.praxisplatform.uischema.controller.docs: Controllers de documentação
  • org.praxisplatform.uischema.service: Serviços base e metadados
  • org.praxisplatform.uischema.filter: Filtros e specifications
  • org.praxisplatform.uischema.configuration: Configurações adicionais

🔧 Fluxo de Inicialização

 Spring Boot Auto-Configuration Detection
              ↓
 PraxisMetadataAutoConfiguration
              ↓
 @ComponentScan escaneia packages
              ↓
 Registra: Controllers, Services, Filters, Configs
              ↓  
 OpenAPI Customizers aplicados
              ↓
 Grupos de infraestrutura criados
              ↓
 Sistema pronto para DynamicSwaggerConfig

🎯 Integração Sistêmica

Esta auto-configuração é a "fundação" que permite que outras funcionalidades funcionem:

  • DynamicSwaggerConfig: Depende do component scan para ser detectado
  • ApiDocsController: Registrado via component scan
  • Services e Utilidades: Serviços base detectados automaticamente
  • Resource controllers: Classes base canônicas e legadas disponibilizadas para heranca

⚡ Ordem de Execução

  1. 1º: PraxisMetadataAutoConfiguration (fundação + component scan)
  2. 2º: OpenApiUiSchemaAutoConfiguration (beans específicos)
  3. 3º: DynamicSwaggerConfig (detectado via component scan, roda via @PostConstruct)
  4. 4º: Validação (executada via @EventListener após startup completo)
Since:
1.0.0
See Also:

  • Constructor Details

    • PraxisMetadataAutoConfiguration

      public PraxisMetadataAutoConfiguration()

  • Method Details

    • bigDecimalOpenApiCustomizer

      @Bean public org.springdoc.core.customizers.OpenApiCustomizer bigDecimalOpenApiCustomizer()

      🔢 Bean OpenApiCustomizer para BigDecimal

      Configura o mapeamento correto de BigDecimal para schemas OpenAPI, garantindo que valores decimais sejam documentados adequadamente na API.

      🎯 Problema Resolvido:

      Por padrão, SpringDoc pode mapear BigDecimal de forma inconsistente. Este customizer força o mapeamento correto para o tipo "number" com formato "decimal".

      📋 Mapeamento Aplicado:

       // Antes (inconsistente):
 BigDecimal → pode ser "string", "number", ou indefinido
 
 // Depois (consistente):
 BigDecimal → "number" com format "decimal"

      🔄 Exemplo de Schema Gerado:

      
 // Campo Java:
 @Schema(description = "Valor do salário")
 private BigDecimal salario;
 
 // Schema OpenAPI resultante:
 {
   "salario": {
     "type": "number",
     "format": "decimal",
     "description": "Valor do salário"
   }
 }

      🎯 Benefícios:

      • Consistência: Todos os BigDecimal mapeados igualmente
      • Precisão: Frontend sabe como tratar valores decimais
      • Validação: Schemas corretos para validação de entrada
      • Documentação: API docs mostram tipos precisos

      🔗 Uso em DTOs:

      
 public class FuncionarioDTO {
     // Automaticamente mapeado como "number"/"decimal":
     private BigDecimal salario;
     private BigDecimal bonus; 
     private BigDecimal desconto;
 }
 
 // Frontend JavaScript pode tratar adequadamente:
 const salario = parseFloat(response.salario); // Não precisa converter de string

      ⚙️ Configuração Técnica:

      Utiliza SpringDocUtils.getConfig().replaceWithSchema() para aplicar o mapeamento globalmente a todas as ocorrências de BigDecimal na aplicação.

      Returns:
      OpenApiCustomizer que configura mapeamento de BigDecimal

    • restApiResourceComponentCustomizer

      @Bean public org.springdoc.core.customizers.GlobalOpenApiCustomizer restApiResourceComponentCustomizer()

    • praxisMetadataInfraOpenApi

      @Bean public org.springdoc.core.models.GroupedOpenApi praxisMetadataInfraOpenApi()

      🏗️ Bean GroupedOpenApi para Infraestrutura do Praxis

      Cria um grupo OpenAPI específico para endpoints de infraestrutura do sistema Praxis Metadata, separando a documentação interna dos endpoints de aplicação.

      🎯 Objetivo:

      Organizar a documentação OpenAPI separando endpoints internos do framework (infraestrutura) dos endpoints específicos da aplicação do usuário.

      📡 Endpoints Incluídos:

      • /schemas/filtered: Resolução automática de schemas por path
      • /schemas/catalog: Catálogo resumido de domínios e superfícies publicadas
      • Outros endpoints futuros em /schemas/*: somente quando realmente implementados pelo starter

      🔄 Padrão de Matching:

       pathsToMatch("/schemas/**")
 
 ✅ Incluídos:
 /schemas/filtered?path=/api/funcionarios
 /schemas/catalog
 
 ❌ Excluídos:
 /api/funcionarios (aplicação)
 /api/departamentos (aplicação)  
 /health (outros sistemas)

      🎪 Benefícios da Separação:

      • Organização: Documentação interna separada da aplicação
      • Clareza: Desenvolvedores veem APIs do framework vs. negócio
      • Manutenção: Mudanças internas não poluem docs da aplicação
      • Versionamento: Infraestrutura pode ter ciclo diferente da aplicação

      📋 Uso no Swagger UI:

       Swagger UI Dropdown:
 ├── praxis-metadata-infra (este grupo)
 │   └── Endpoints: /schemas/filtered, /schemas/{group}
 ├── application (próximo bean)  
 │   └── Endpoints: /api/funcionarios, /api/departamentos
 └── api-human-resources-funcionarios (grupos dinâmicos)
     └── Endpoints: /api/human-resources/funcionarios/**

      🔗 Integração:

      Este grupo é consumido pelo OpenApiGroupResolver junto com outros grupos, mas tem prioridade diferente por ser específico de infraestrutura.

      ⚡ Performance:

      Documento pequeno (~2-5KB) focado apenas nos endpoints de infraestrutura, carregamento rápido para desenvolvedores que querem entender a API interna do framework.

      Returns:
      GroupedOpenApi configurado para endpoints de infraestrutura Praxis

    • praxisMetadataApplicationOpenApi

      @Bean public org.springdoc.core.models.GroupedOpenApi praxisMetadataApplicationOpenApi()

      🌐 Bean GroupedOpenApi para Aplicação Geral

      Cria um grupo OpenAPI "fallback" que captura todos os endpoints da aplicação que não são específicos de infraestrutura nem foram capturados por grupos dinâmicos mais específicos.

      🎯 Objetivo:

      Fornecer um grupo de documentação "catch-all" para endpoints que não se encaixam em grupos mais específicos, garantindo que nenhuma API fique sem documentação.

      📡 Endpoints Incluídos:

       pathsToMatch("/**")           // Inclui TODOS os paths
 pathsToExclude("/schemas/**") // EXCETO infraestrutura
 
 ✅ Resultado - Incluídos:
 /api/funcionarios/**     (se não tiver grupo dinâmico mais específico)
 /api/departamentos/**    (se não tiver grupo dinâmico mais específico)
 /health                  (endpoints de sistema)
 /actuator/**             (se habilitado)
 /api/custom/**           (endpoints customizados)
 
 ❌ Excluídos:
 /schemas/**              (grupo praxis-metadata-infra)

      🔄 Hierarquia de Grupos (Ordem de Prioridade):

      1. Grupos Dinâmicos: Criados pelo DynamicSwaggerConfig (mais específicos)
      2. Infraestrutura: praxis-metadata-infra (/schemas/**)
      3. Application: Este grupo (fallback geral)

      📋 Cenários de Uso:

       Cenário 1 - Controller com @ApiResource:
 @ApiResource("/api/funcionarios") 
 → DynamicSwaggerConfig cria grupo específico
 → NÃO aparece no grupo "application"
 
 Cenário 2 - Controller sem @ApiResource:
 @RestController @RequestMapping("/api/legacy")
 → NÃO tem grupo específico criado
 → APARECE no grupo "application" 
 
 Cenário 3 - Endpoints de sistema:
 /health, /actuator/info
 → APARECE no grupo "application"

      🎪 Benefícios:

      • Cobertura Total: Nenhum endpoint fica sem documentação
      • Fallback Seguro: Endpoints legados ainda são documentados
      • Debugging: Facilita identificar endpoints não organizados
      • Migração Gradual: Permite transição suave para @ApiResource

      ⚠️ Indicador de Migração:

      Se endpoints de negócio aparecem neste grupo em vez de grupos específicos, é um indicador de que o controller precisa migrar para usar @ApiResource:

      
 // ❌ Aparece no grupo "application":
 @RestController
 @RequestMapping("/api/funcionarios") 
 
 // ✅ Tem grupo próprio "api-funcionarios":
 @ApiResource("/api/funcionarios")

      📊 Exemplo no Swagger UI:

       Dropdown Swagger UI:
 ├── api-human-resources-funcionarios (específico)
 ├── api-human-resources-departamentos (específico)  
 ├── praxis-metadata-infra (infraestrutura)
 └── application (este grupo - fallback)
     ├── /health
     ├── /actuator/info  
     └── /api/legacy/** (controllers não migrados)

      🔗 Integração com Resolução Automática:

      O OpenApiGroupResolver também considera este grupo, mas com menor prioridade que grupos mais específicos, garantindo que a resolução automática funcione corretamente.

      Returns:
      GroupedOpenApi configurado como fallback para todos os endpoints da aplicação