Package org.praxisplatform.uischema.annotation

Annotation Interface ApiResource

@Target(TYPE) @Retention(RUNTIME) @RestController @RequestMapping public @interface ApiResource
Meta-anotacao canonica para declarar um recurso REST da plataforma.

@ApiResource combina RestController e RequestMapping e passa a ser a fonte de verdade do recurso em tres eixos complementares:

  • path REST do recurso, publicado no OpenAPI e usado pelos controllers canonicos;
  • identidade semantica estavel via resourceKey(), usada por discovery;
  • metadados basicos para scanner OpenAPI, HATEOAS e resolucao de schemas filtrados.

A distincao entre path e resourceKey e intencional:

  • o path diz onde o recurso vive operacionalmente, por exemplo /api/human-resources/employees;
  • o resourceKey diz qual recurso a plataforma esta tratando semanticamente, por exemplo human-resources.employees.

No baseline atual, o resourceKey e a chave usada para catalogos de surfaces/actions, snapshots de capabilities e availability contextual. Por isso ele nao deve variar apenas porque a URL operacional do recurso mudou.

No core atual do starter, esta e a forma recomendada de expor controllers que herdam AbstractResourceController, AbstractResourceQueryController ou AbstractReadOnlyResourceController. Ela evita que path e identidade do recurso fiquem espalhados por convencoes paralelas.

Exemplo recomendado


 @ApiResource(
     value = "/api/human-resources/employees",
     resourceKey = "human-resources.employees"
 )
 @ApiGroup("human-resources")
 public class EmployeeController extends AbstractResourceController<...> {
 }

Nao e necessario combinar @ApiResource com @RestController; a meta-anotacao ja incorpora esse papel. Quando houver necessidade de agrupamento documental explicito, combine com ApiGroup.

See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    resourceKey
    Identidade semantica estavel do recurso.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    consumes
    Define os content types consumidos pelo recurso.
    String[]
    path
    Alias para value() para maior clareza.
    String[]
    produces
    Define os content types produzidos pelo recurso.
    String[]
    value
    Define o path do recurso.

  • Element Details

    • value

      @AliasFor(annotation=org.springframework.web.bind.annotation.RequestMapping.class, attribute="value") String[] value
      Define o path do recurso. Recomenda-se criar constantes especificas da aplicacao em vez de repetir literais espalhados no codigo.
      Returns:
      o path do recurso
      Default:
      {}

    • path

      @AliasFor(annotation=org.springframework.web.bind.annotation.RequestMapping.class, attribute="path") String[] path
      Alias para value() para maior clareza.
      Returns:
      o path do recurso
      Default:
      {}

    • resourceKey

      String resourceKey
      Identidade semantica estavel do recurso.

      Este valor e usado por superficies derivadas de discovery, como os catalogos de surfaces e actions, alem dos snapshots de capabilities. Diferentemente do path REST, ele nao deve variar apenas porque a URL operacional mudou.

      Returns:
      chave semantica estavel do recurso

    • produces

      @AliasFor(annotation=org.springframework.web.bind.annotation.RequestMapping.class, attribute="produces") String[] produces
      Define os content types produzidos pelo recurso. Por padrao, produz JSON.
      Returns:
      os media types produzidos
      Default:
      {"application/json"}

    • consumes

      @AliasFor(annotation=org.springframework.web.bind.annotation.RequestMapping.class, attribute="consumes") String[] consumes
      Define os content types consumidos pelo recurso. Por padrao, nao especifica content types e aceita todos.
      Returns:
      os media types consumidos
      Default:
      {}