Classe RestDoc (oDoc)

A classe RestDoc (tlpp.doc) é o objeto nativo que o REST_DOC instancia e entrega por parâmetro à sua função de documentação. Com ele você descreve título, parâmetros, body e respostas sem precisar conhecer a estrutura JSON interna — o próprio objeto serializa tudo ao final.

Versão mínima

Recurso disponível a partir da versão 01.07.01 do tlppCore.

Como receber o objeto

#include 'tlpp-doc.th'

function U_meuEndpoint_DOC( oDoc )

  // Validação recomendada
  if ( !valtype(oDoc) == "O" .or. !MethIsMemberOf(oDoc,"isa") .or. !oDoc:isa("RestDoc") )
    return ""
  endif

  oDoc:setTitle("Meu endpoint")
  oDoc:addDescription("Descrição da API.")
  // ... parâmetros, body, respostas

return

O include tlpp-doc.th é obrigatório — ele define as constantes de localização (_query_, _path_, _header_) e tipo (_char_, _int_, _numeric_, _logical_).

---

Constantes disponíveis (tlpp-doc.th)

Grupo	Constante	Significado
Localização (in)	_query_	Query String
	_path_	Path Param
	_header_	Header HTTP
Tipo do parâmetro	_char_	character
	_int_	integer
	_numeric_	number
	_logical_	boolean
Content-type (body)	_json_	application/json
	_xml_	application/xml
	_csv_	text/csv
	_txt_	text/plain

---

Verificação de tipo

Verificação de tipo do objeto RestDoc.

Retorna .T. se cClassName for "restdoc" ou "rest_doc" (case-insensitive). Use para verificar se o objeto recebido por parâmetro é do tipo correto antes de utilizá-lo.

Retorno	logical
Descrição	Verdadeiro quando o nome informado corresponde à classe RestDoc.

---

Tratamento de erros

Consultar erros ocorridos durante a construção da documentação.

Retorna .T. se houver um erro registrado durante a construção da documentação.

Retorno	logical
Descrição	Verdadeiro quando existe ao menos um erro.

---

Título

Definir e consultar o título do endpoint documentado.

Define o título do endpoint. Retorna .F. se o valor informado for vazio.

Retorno	logical
Descrição	Verdadeiro quando o título foi definido com sucesso.

---

Descrição

Construir descrições multi-linha para o endpoint.

Adiciona uma linha de descrição ao endpoint. Pode ser chamado várias vezes para compor texto multi-linha. Retorna .F. se a string for vazia.

Retorno	logical
Descrição	Verdadeiro quando a linha foi adicionada.

---

Parâmetros (query, path, header)

Documentar parâmetros de entrada recebidos via query string, path param ou header HTTP.

Cria um novo parâmetro e retorna seu índice numérico. Use esse índice nos demais métodos setParam*.

Retorno	numeric
Descrição	Índice do parâmetro criado.

---

Body (Request Body)

Documentar o corpo da requisição HTTP — content-type, obrigatoriedade e componentes.

Define descrição, obrigatoriedade e content-type do body de uma vez (forma compacta).

Retorno	logical
Descrição	Verdadeiro quando definido com sucesso.

---

Respostas (Responses)

Documentar os possíveis retornos HTTP do endpoint — status codes, descrições e componentes.

Cria uma nova resposta e retorna seu índice. Ambos parâmetros são opcionais — podem ser informados aqui ou via setters individuais.

Retorno	numeric
Descrição	Índice da resposta criada.

---

Exportação

Gerar o JSON final de documentação. Uso interno do REST_DOC — o desenvolvedor normalmente não precisa chamar.

Gera o JSON de documentação no formato esperado pelo REST_DOC. O parâmetro é passado por referência e recebe o resultado. Para o desenvolvedor final, esse método não precisa ser utilizado pois o REST_DOC o invoca internamente.

Retorno	logical
Descrição	Verdadeiro se o JSON foi gerado com sucesso.

Método de uso interno. O REST_DOC chama toJson() automaticamente ao final da execução da função DOC.

---

Exemplos no GitHub

Exemplo	O que demonstra
Básico com objeto	oDoc com parâmetros e respostas simples
Avançado com objeto	Todos os recursos: enum, body, componentes, i18n

Exemplo no GitHub

totvs/tlpp-sample-rest-documentation — src/rest/03_dedicated_function_doc/basic/restdoc_object_return.tlpp

Próximo passo: List dinâmico