Metadado description

É o metadado central do REST-DOC. Ele diz ao motor de onde vem a documentação do endpoint — pode ser um texto simples, uma função que retorna JSON ou um ID de tradução.

Três modos

Texto direto

Coloque o texto entre aspas. O valor vai direto para o campo description do OpenAPI.

description="Exemplo de documentação simples, somente descrição"

Útil quando a API precisa de poucas linhas de explicação.

Função [nome]

Aponte para uma função TLPP entre colchetes. O motor executa a função e usa o JSON retornado como documentação completa do endpoint.

description="[U_rest_sample_04_basic_DOC]"

A função deve estar compilada no mesmo ambiente e retornar um JSON válido.

ID i18n <N>

Use um número entre <> para referenciar um bloco TRANSLATE em um arquivo i18n. O JSON de documentação fica fora do fonte REST.

description="<1>"

O ID corresponde ao número do TRANSLATE 1#URI#BRA# { ... }.

endpoint vs description

Metadado	Papel
endpoint	Imperativo — registra a rota no AppServer
description	Informativo — alimenta apenas o REST-DOC

Regras

• Função DOC: nome entre colchetes [NomeFuncao]
• i18n: número entre <> — conteúdo no arquivo *-i18n.tlpp
• Multi-linha: use description1, description2, … no JSON (sem description simples no mesmo objeto); a sequência numérica deve ser contínua

Exemplo no GitHub

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

Exemplos no GitHub

Fontes .tlpp da abordagem: Annotation tradicional.