FAQ - Praxis Metadata Starter

Perguntas frequentes sobre contrato metadata-driven, /schemas/filtered, runtime Angular oficial e trilha publica de guias.

Indice rapido

O que e o Praxis Metadata Starter?
Como comecar do jeito canonico?
Como usar /schemas/filtered?
Como os grupos OpenAPI sao resolvidos?
Quando usar /options/filter e /options/by-ids?
Como modelar filtros com @Filterable?
Como expor views e recursos read-only?
Existe um runtime Angular oficial?
Como funciona cache e ETag em /schemas/filtered?
Como personalizar e publicar o Javadoc?
Quais projetos publicos fazem parte do ecossistema?

O que e o Praxis Metadata Starter?

E o modulo canonico da plataforma Praxis para publicar contratos metadata-driven no backend. Ele enriquece o OpenAPI com x-ui, expõe superficies como /schemas/filtered e fornece controllers, services e repositorios base para CRUD, filtros, options e documentacao.

Como comecar do jeito canonico?

A trilha principal de implementacao esta publicada no GitHub Pages e deve ser a primeira referencia para pessoas e LLMs:

Como usar /schemas/filtered?

Use GET /schemas/filtered com path, operation e schemaType para obter o schema de request ou response enriquecido com x-ui.

curl -i "http://localhost:8080/schemas/filtered?path=/api/human-resources/pessoas/all&operation=get&schemaType=response"

curl -i "http://localhost:8080/schemas/filtered?path=/api/human-resources/pessoas/filter&operation=post&schemaType=request"

Referencia de API: ApiDocsController.

Como os grupos OpenAPI sao resolvidos?

O starter combina grupos individuais por recurso, grupos agregados por contexto e um fallback application. A resolucao automatica por path usa o best match mais especifico disponivel.

Referencias: DynamicSwaggerConfig e OpenApiGroupResolver.

Quando usar /options/filter e /options/by-ids?

POST /options/filter: para popular combos e autocomplete com busca paginada.
GET /options/by-ids: para reidratar labels de valores ja selecionados, preservando a ordem dos IDs.

Referencias: OptionDTO e Endpoints Overview.

Como modelar filtros com @Filterable?

Crie um DTO de filtro e anote os campos com @Filterable, informando a operacao e, quando necessario, a relacao no formato "a.b.campo". O builder converte o DTO em Specifications JPA.

Referencias: Filterable e filters-overview.

Como expor views e recursos read-only?

Use AbstractReadOnlyService e AbstractReadOnlyController. Os endpoints de leitura, filtros, options e locate continuam disponiveis; escritas retornam 405 Method Not Allowed por design.

Guia publico: READ-ONLY-VIEWS.

Existe um runtime Angular oficial?

Sim. O repositorio publico praxis-ui-angular publica as bibliotecas @praxisui/* usadas para consumir /schemas/filtered e renderizar formularios e tabelas a partir do vocabulario x-ui.

# exemplo de instalacao em um host Angular novo
npm install @praxisui/core @praxisui/table @praxisui/dynamic-form @praxisui/crud

Guia publico: Guia 03 - Frontend - Angular CRUD Completo.

Como funciona cache e ETag em /schemas/filtered?

O starter expõe ETag e X-Schema-Hash para revalidacao condicional via If-None-Match. Quando nada muda, o endpoint pode responder 304 Not Modified sem corpo.

Referencias: IfNoneMatchUtils e SchemaIdBuilder.

Como personalizar e publicar o Javadoc?

Edite src/main/javadoc/overview.html e os arquivos em src/main/javadoc/doc-files/. A publicacao no GitHub Pages e feita pelo workflow .github/workflows/docs.yml, que gera o Javadoc, converte os arquivos Markdown de docs/ em HTML e publica tudo junto.