Home
O que é o Gerador de Documentação tlppCore?
O gerador de documentação é uma ferramenta nativa do tlppCore* e TLPP**, na qual permite ao desenvolvedor criar documentações técnicas de suas APIS de forma simples, podendo gerar o documento final em diversos formatos.
O motor é capaz de capturar as informações adicionadas nas annotations de seus serviços e organizá-los em um único documento em formato específico, como por exemplo: swagger.
(*) tlppCore é um framework nativo da linguagem TLPP que contém diversas ferramentas, módulos e facilitadores para os desenvolvedores AdvPL e TLPP. Saiba mais no artigo: TLPP X tlppCore: O que é cada um?
(**) TLPP (TOTVS Language Plus Plus) é uma linguagem de programação de propriedade da TOTVS S/A, para saber mais, acesse: A Linguagem TLPP
Manual de Uso
DISCLAIMER
O módulo REST-DOC é um recurso extremamente novo no tlppCore e ainda está em fase de implementação. O produto está recebendo contantes ajustes, melhorias e, portanto, sua documentação ainda está em fase de construção.
Agradecemos o interesse em avaliar o produto, e nos colocamos à inteira disposição para eventuais dúvidas.
Por favor, usufruam do recurso de abertura de Issues para esse projeto!
Se você já criou algum serviço REST do tlppCore sabe que é utilizado o recurso de annotation em TLPP para sinalizar uma função ou classe como um serviço válido de REST.
Porém, até hoje só tínhamos utilizado o metadado 'endpoint' para determinar o endpoint do serviço. Vejamos o exemplo:
@get(endpoint="/exemplo01")
user function Exemplo01()
return oRest:SetResponse("ok")Ou, de forma simplificada:
@get("/exemplo01")
user function Exemplo01()
return oRest:SetResponse("ok")Agora iremos adicionar mais um metadado, o description.
Claramente por ele iremos, através de um texto, definir uma descrição sobre o serviço REST criado, vejamos o exemplo:
@get(endpoint="/exemplo01",description="API REST GET de exemplo, responde OK e possui uma breve descrição.")
user function Exemplo01()
return oRest:SetResponse("ok")Somente isso já seria suficiente para incluir essa API na captura pelo motor REST-DOC, gerando um documento swagger conforme abaixo:
openapi: 3.0.3
info:
title: APIs REST
description: |-
Lista de APIs REST disponibilizadas pelo TOTVS appServer.
Port: [8080]
version: 0.1.1
paths:
/exemplo01:
get:
description: API REST GET de exemplo, responde OK e possui uma breve descrição.
responses:
200:
description: SucessoVeja como é simples iniciar nesse processo de documentar suas APIs!
Veja exemplo no projeto: src/rest/basic/sample_01_basic.tlpp
Mas isso seria suficiente para alguém entender como utilizar sua API? E para os casos que recebemos parâmetros? QueryString, Header, Body e PathParam? E para retornos distintos? E recebimentos e retornos de dados estruturados? Posso também localizar meus textos para outros idiomas?
Sim, há respostas para todas as questões acima e iremos respondê-las nas próximas páginas.
Como visto acima, podemos informar a descrição do serviço REST através desse MetaDado, mas é somente isso que podemos fazer?
Não, o MetaDado description é uma chave coringa nesse processo de documentação, pois através dele podemos indicar que a documentação está definida em uma função específica ou em um arquivo de i18n indicando o ID de captura do texto.
Importante ressaltar que ambos os casos citados acima o retorno precisa ser um texto em formato JSON, mas não se preocupe ainda que mais adiante iremos falar especificamente da sintaxe esperada.
Para informar que as informações do Serviço REST serão capturadas por uma função TLPP, no MetaDado description colocamos o nome da função entre colchetes, como segue:
@Get(endpoint="/exemplo02",description="[U_rest_exemplo02_DOC]")
user function Exemplo02()
return oRest:SetResponse("ok")Notem que em description do serviço não foi informado aum texto com a descrição, e sim um nome de uma função entre colchetes.
Dessa forma, o motor identifica que ele precisa executar essa função para obter as informações do serviço.
Mas, então o que devemos implementar nessa função e qual ser retorno?
Abaixo segue a implementação desse exemplo simplificado na qual somente informamos a descrição.
user function U_rest_exemplo02_DOC() as character
local cJson := '' as character
TOSTRING cJson#;
{ ;
"description" : "API REST GET de exemplo, responde OK e possui uma breve descrição que foi definida em uma função retornando um JSON"
}
return cJsonNote que aqui não precisamos repetir o EndPoint pois o motor já conseguirá associar ao endpoint correto.
Veja exemplo no projeto: src/rest/basic/sample_04_basic_by_function.tlpp
em construção ...