Pular para o conteúdo principal

Metadados da annotation REST

As annotations @Get e @Put aceitam metadados que o motor REST-DOC converte em OpenAPI. Alguns são funcionais (registram a rota); outros são informativos (só documentação).

Propriedades​

MetadadoPara que serve
endpointPath da rota REST — obrigatório para registrar o serviço
descriptionOrigem da documentação — ver description
titleTítulo legível do endpoint no OpenAPI
paramsParâmetros (query, path, header) como string JSON
responsesRespostas HTTP (statusCode, description) como string JSON

params e responses inline​

Quando a documentação é simples, você pode declarar parâmetros e respostas direto na annotation, sem função DOC:

@Get(;
  endpoint="/rest/sample/doc/basic/02",;
  description="...",;
  title="DOC simples 02",;
  params='[{"name":"param1","in":"query",...}]',;
  responses='[{"statusCode":200,"description":"OK"},...]';
)

Em documentações mais ricas (função _DOC), o JSON suporta campos extras como minimum, maximum, values e requestBody.

Exemplo no GitHub

totvs/tlpp-sample-rest-documentation — src/rest/01_traditional_annotation/extended_annotation.tlpp

Exemplos no GitHub​

Fontes .tlpp da abordagem: Annotation tradicional.