Package org.praxisplatform.uischema.annotation

Annotation Interface ApiGroup

@Target(TYPE) @Retention(RUNTIME) public @interface ApiGroup
Anotação opcional para definir explicitamente o grupo OpenAPI de um controller.

No contrato atual da plataforma, @ApiGroup e usado para estabilizar a navegacao da documentacao publica sem depender apenas da derivacao automatica pelo nome do controller ou pelo path do recurso. Isso e especialmente util quando varios recursos pertencem ao mesmo contexto de negocio e devem aparecer agrupados sob a mesma superficie OpenAPI.

Quando usar

  • Quando o nome do grupo precisa refletir um bounded context de negocio, e nao apenas o path.
  • Quando varios controllers devem compartilhar o mesmo agrupamento documental.
  • Quando a plataforma publica docs por grupos estaveis consumidos por UI, recipes ou integradores.

Exemplo recomendado


 @ApiResource(ApiPaths.HumanResources.FUNCIONARIOS)
 @ApiGroup("human-resources")
 public class FuncionarioController extends AbstractResourceController<...> {
     // heranca + wiring do service
 }

No exemplo acima, o grupo OpenAPI publicado passa a ser human-resources, o que ajuda a manter uma URL de docs mais estavel, por exemplo /v3/api-docs/human-resources, mesmo quando a convencao automatica derivada do nome da classe nao seria a mais adequada.

A anotacao nao altera o path REST do recurso. Ela afeta a organizacao documental e a resolucao de grupos feita pela infraestrutura OpenAPI do starter.

See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    Nome canônico do grupo OpenAPI para este controller.

  • Element Details

    • value

      String value
      Nome canônico do grupo OpenAPI para este controller.

      O valor informado sera usado como identificador do grupo na documentacao OpenAPI, aparecendo tipicamente em URLs no formato /v3/api-docs/{value} e na resolucao de metadados documentais do recurso.

      Recomenda-se usar nomes estaveis e semanticamente claros, como human-resources, catalog ou reporting, evitando acoplamento acidental ao nome tecnico da classe.

      Returns:
      o nome do grupo OpenAPI publicado para o controller