Praxis Metadata Starter — API Javadoc

Praxis Metadata Starter

Biblioteca canonica da plataforma Praxis para publicar contratos metadata-driven no backend. O starter enriquece o OpenAPI com x-ui, expõe superficies como /schemas/filtered e fornece infraestrutura base para CRUD, filtros, options, documentacao filtrada e consumo por runtimes e LLMs.

Modelando DTO com @UISchema

Labels, tipos, validacoes e dicas refletidas no OpenAPI.

Expondo controller com @ApiResource

Controllers base com endpoints prontos e documentacao filtrada.

Consumindo /schemas/filtered

Schemas de request e response com ETag para UIs estaveis.

FAQ

Perguntas frequentes sobre grupos, cache, filtros e runtime Angular.

Ecossistema

Node, gerador x-ui, runtime Angular oficial e outros projetos publicos.

Runtime Angular Oficial

Bibliotecas publicas @praxisui para consumir /schemas/filtered e x-ui.

Uploads e arquivos: este starter trata de metadados de UI, contrato e documentacao. Gestao de arquivos pertence ao modulo dedicado do ecossistema.

Fluxo recomendado de implementacao

• Guia 01 - Backend - Aplicacao Nova
• Guia 02 - Backend - CRUD Metadata-Driven
• Guia 03 - Frontend - Angular CRUD Completo
• Checklist de Validacao

O que este starter entrega

• Controllers base com endpoints de CRUD, filtros, options e schemas.
• Contrato enriquecido com x-ui a partir de anotações Java e Bean Validation.
• Suporte a grupos OpenAPI e leitura filtrada por /schemas/filtered.
• Filtros metadata-driven com @Filterable e Specifications JPA.
• Read-only views com AbstractReadOnlyController e AbstractReadOnlyService.
• Headers de cache e ETag para revalidacao condicional de schemas.

Como comecar

<dependency>
  <groupId>io.github.codexrodrigues</groupId>
  <artifactId>praxis-metadata-starter</artifactId>
  <version>5.0.0-rc.2</version>
</dependency>

Depois, anote DTOs com @UISchema, exponha controllers com @ApiResource e siga os guias publicados no GitHub Pages para fechar o fluxo completo.

Referencias importantes

• GitHub Pages / Docs
• Hub dos guias
• FAQ
• Ecossistema
• Repositorio publico do runtime Angular oficial

Packages

Package	Description
org.praxisplatform.uischema	Núcleo do Praxis Metadata Starter com enums, propriedades e contratos que descrevem o vocabulário x-ui compartilhado entre backend e frontend.
org.praxisplatform.uischema.action
org.praxisplatform.uischema.analytics
org.praxisplatform.uischema.annotation	Conjunto de anotações que descrevem recursos REST, agrupamentos OpenAPI e metadados de interface x-ui.
org.praxisplatform.uischema.capability
org.praxisplatform.uischema.configuration	Auto-configuracoes Spring Boot do starter.
org.praxisplatform.uischema.constants	Constantes compartilhadas entre controladores, serviços e utilitários para manter consistência em paths e nomes de recursos.
org.praxisplatform.uischema.controller.base	Camada base de controllers REST metadata-driven da plataforma.
org.praxisplatform.uischema.controller.docs	Endpoints e componentes que publicam documentacao OpenAPI enriquecida.
org.praxisplatform.uischema.dto	DTOs utilitarios e contratos leves usados pela superficie publica do starter.
org.praxisplatform.uischema.extension	Extensoes do pipeline OpenAPI/SpringDoc para gerar contratos enriquecidos com x-ui.
org.praxisplatform.uischema.extension.annotation	Anotações responsáveis por descrever metadados x-ui aplicados a campos de DTOs e entidades.
org.praxisplatform.uischema.filter.annotation	Anotações que marcam campos e DTOs como participantes do mecanismo de filtros dinâmicos.
org.praxisplatform.uischema.filter.dto	DTOs, contratos e adaptadores utilizados para construir filtros dinâmicos a partir de anotações @Filterable.
org.praxisplatform.uischema.filter.range
org.praxisplatform.uischema.filter.relativeperiod
org.praxisplatform.uischema.filter.specification	Implementacoes de Specification e builders que convertem DTOs anotados em consultas dinamicas.
org.praxisplatform.uischema.filter.web
org.praxisplatform.uischema.hash	Funções e utilitários para canonização e hash de schemas OpenAPI, garantindo identificadores e ETags estáveis.
org.praxisplatform.uischema.http	Utilitários HTTP utilizados pelos controladores de documentação e respostas padronizadas.
org.praxisplatform.uischema.id	Utilitários para construção de identificadores e nomes estáveis usados em schemas, endpoints e links.
org.praxisplatform.uischema.mapper.base	Mapeadores base (MapStruct) para conversão entre entidades, DTOs e opções de UI.
org.praxisplatform.uischema.mapper.config	Configurações compartilhadas de mapeamento (MapStruct), como estratégias de nomeação, nullability e políticas de atualização.
org.praxisplatform.uischema.numeric	Tipos e helpers utilizados para formatar campos numéricos em formulários e relatórios.
org.praxisplatform.uischema.openapi
org.praxisplatform.uischema.options
org.praxisplatform.uischema.options.service
org.praxisplatform.uischema.options.service.jpa
org.praxisplatform.uischema.repository.base	Repositórios base para operações CRUD e consultas dinâmicas via Specification.
org.praxisplatform.uischema.rest.exceptionhandler	Tratamento consistente de erros REST, incluindo categorias e detalhes padronizados para respostas da API.
org.praxisplatform.uischema.rest.exceptionhandler.exception	Exceções específicas expostas pelo manipulador global de erros.
org.praxisplatform.uischema.rest.response	Modelos canonicos de resposta REST da plataforma.
org.praxisplatform.uischema.schema
org.praxisplatform.uischema.service.base	Serviços base que orquestram repositórios, Specifications e convenções corporativas.
org.praxisplatform.uischema.service.base.annotation	Anotações auxiliares usadas por serviços base (ex.: ordenação padrão).
org.praxisplatform.uischema.stats
org.praxisplatform.uischema.stats.dto
org.praxisplatform.uischema.stats.service
org.praxisplatform.uischema.stats.service.jpa
org.praxisplatform.uischema.surface
org.praxisplatform.uischema.util	Utilitarios estruturais do starter.
org.praxisplatform.uischema.validation