Package org.praxisplatform.uischema.configuration

Class DynamicSwaggerConfig

java.lang.Object
org.praxisplatform.uischema.configuration.DynamicSwaggerConfig
@Configuration public class DynamicSwaggerConfig extends Object

🎯 Configuração Dinâmica de Grupos OpenAPI com Estratégia Dupla

Cria automaticamente grupos OpenAPI otimizados para performance usando uma estratégia dupla: Grupos Individuais Ultra-Específicos para CRUDs + Grupos Agregados por Contexto via @ApiGroup.

🎯 Problema Resolvido

Antes desta implementação, era necessário registrar grupos OpenAPI manualmente e especificar parâmetros 'document' no ApiDocsController. Esta classe resolve automaticamente ambos os problemas com performance otimizada.

🚀 Estratégia Dupla de Grupos

📊 1. Grupos Individuais Ultra-Específicos

  • Escopo: Controllers do legado AbstractCrudController e da nova hierarquia AbstractResourceQueryController
  • Performance: ~3-5KB por documento (ultra-rápido)
  • Uso: Consultas específicas como /schemas/filtered?path=/api/human-resources/eventos-folha/all

🏷️ 2. Grupos Agregados por Contexto

  • Escopo: QUALQUER controller com anotação @ApiGroup
  • Performance: ~50-100KB por documento (ainda otimizado)
  • Uso: Visualização de contextos completos no Swagger UI

🔄 Fluxo de Funcionamento

  1. Startup da Aplicação: @PostConstruct é executado automaticamente
  2. Escaneamento Dual:
    • 1ª passada: Identifica controllers resource-oriented canônicos para grupos individuais
    • 2ª passada: Identifica QUALQUER controller com @ApiGroup para grupos agregados
  3. Extração de Paths: Usa AnnotationUtils para detectar @ApiResource/@RequestMapping
  4. Registro Inteligente: Evita duplicação de beans e otimiza padrões agregados

📋 Exemplos de Uso


 // ✅ CRUD Controller - Cria grupo individual + participa do agregado
 @ApiResource("/api/human-resources/funcionarios")
 @ApiGroup("human-resources") 
 public class FuncionarioController extends AbstractCrudController<...> {
     // Grupo individual: "api-human-resources-funcionarios" (ultra-específico)
     // Grupo agregado: "recursos-humanos" (contexto completo)
 }
 
 // ✅ Bulk Controller - Apenas participa do grupo agregado
 @ApiResource("/api/human-resources/funcionarios")
 @ApiGroup("human-resources-bulk")
 public class FuncionarioBulkController extends AbstractBulkController<...> {
     // Grupo agregado: "recursos-humanos-bulk" (contexto bulk)
 }
 
 // ✅ Qualquer Controller - Participa apenas do grupo agregado
 @RestController
 @RequestMapping("/api/custom/reports")
 @ApiGroup("relatorios")
 public class CustomReportController {
     // Grupo agregado: "relatorios" (contexto customizado)
 }

📊 Resultado Típico

Para uma aplicação com 8 controllers CRUD e 8 controllers Bulk:

 📋 Grupos Individuais (8):
 ├── api-human-resources-funcionarios     (3KB - ultra-rápido)
 ├── api-human-resources-cargos          (3KB - ultra-rápido) 
 ├── api-human-resources-departamentos   (3KB - ultra-rápido)
 └── ... (5 mais)
 
 🏷️ Grupos Agregados (2):
 ├── recursos-humanos        (50KB - 8 controllers CRUD)
 └── recursos-humanos-bulk   (30KB - 8 controllers Bulk)
 
 📈 Total: 10 grupos vs documento completo (500KB+)

🚀 Benefícios

  • Performance Extrema: Grupos individuais ~99% menores que documento completo
  • Flexibilidade Total: Qualquer controller pode participar de contextos via @ApiGroup
  • Semântica Clara: Grupos individuais para CRUDs, agregados para contextos
  • Zero Configuração: Detecção automática de anotações @ApiResource/@RequestMapping
  • Integração Perfeita: ApiDocsController resolve grupos automaticamente

⚙️ Configuração Necessária

Esta classe deve estar incluída no @ComponentScan da PraxisMetadataAutoConfiguration:


 @ComponentScan(basePackages = {"org.praxisplatform.uischema.configuration"})
Since:
1.0.0
See Also:

  • Constructor Details

    • DynamicSwaggerConfig

      public DynamicSwaggerConfig()

  • Method Details

    • createDynamicGroups

      @PostConstruct public void createDynamicGroups()

      🎯 Método Principal - Criação Dinâmica com Estratégia Dupla

      Este método é executado automaticamente durante o startup da aplicação (@PostConstruct) e implementa a estratégia dupla de criação de grupos:

      📊 1ª Passada - Grupos Individuais Ultra-Específicos:

      • Escaneia controllers que estendem AbstractCrudController ou AbstractResourceQueryController
      • Cria grupos individuais baseados no path completo (ex: "api-human-resources-funcionarios")
      • Performance ultra-otimizada: ~3-5KB por documento

      🏷️ 2ª Passada - Grupos Agregados por Contexto:

      • Escaneia TODOS os controllers em busca de anotação @ApiGroup
      • Agrupa controllers por contexto de negócio (ex: "recursos-humanos", "recursos-humanos-bulk")
      • Calcula padrões agregados inteligentes que englobam múltiplos paths

      📊 Exemplo de Saída no Log:

       Total de handlers encontrados: 247
 Controllers qualificados para grupos individuais canônicos: 8
 Grupo individual 'api-human-resources-funcionarios' registrado para FuncionarioController
 Grupo individual 'api-human-resources-cargos' registrado para CargoController
 ... (6 mais grupos individuais)
 
 Grupo agregado 'recursos-humanos' registrado com 8 controller(s) (pattern: /api/human-resources)
 Grupo agregado 'recursos-humanos-bulk' registrado com 8 controller(s) (pattern: /api/human-resources)
 
 Total: 10 grupos (8 individuais + 2 agregados)

      🚀 Performance Resultante:

      • Consultas específicas: 3-5KB (grupos individuais)
      • Contextos de negócio: 50-100KB (grupos agregados)
      • Vs documento completo: 500KB+ (90-99% de economia)

    • validateApiResourceUsage

      @EventListener(org.springframework.boot.context.event.ApplicationReadyEvent.class) public void validateApiResourceUsage()

      ✅ Validação de Conformidade com @ApiResource

      Executa após o startup completo da aplicação para validar se todos os controllers resource-oriented canônicos estão usando @ApiResource conforme esperado.

      🎯 Objetivo:

      Garantir que developers sigam o padrão arquitetural correto, evitando inconsistências e problemas de manutenção futuros. Força migração para @ApiResource para aproveitar os benefícios da resolução automática de grupos OpenAPI.

      📋 Comportamentos:

      • WARN: Emite warnings informativos no log (padrão)
      • FAIL: Interrompe o startup com exceção
      • IGNORE: Pula a validação completamente

      ⚠️ Sem Exceções:

      Todos os controllers resource-oriented canônicos devem migrar para @ApiResource. Não há anotação de exceção ou contorno - a validação é direta e obrigatória.