Home

REST DOC

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!

---

Início

Se você já criou algum serviço REST do tlppCore sabe que é utilizado o recurso de annotation em TLPP para marcar 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, em sua forma minimalista:

@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: Sucesso

Veja como é simples iniciar nesse processo de documentar suas APIs!

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.

Metadado DESCRIPTION

em construção...