Não dependa do Swagger para documentar seus aplicativos RESTful

[Christian Figueiredo]

Eae pessoal. Como vão?

Quando postei sobre as boas práticas de elaboração dos componentes REST, incluí uma dica referente à documentação que seria incluir uma função (UDF) para retornar o escopo variables e receber a representação estrutural.

Essa prática era ótima até descobrir uma função do ColdFusion que faça bem mais: a GetComponentMetaData(). Essa função, além de listar todas as UDF's do componente, lista as propriedades <cfproperty> do objeto, além dos atributos da tag <cfcomponent>, incluindo o displayName e o hint que nos ajudam (e muito) no esclarecimento, até antes de fazer um debug ou uma melhoria no código.

Creio que, com o uso dessa função, será possível construir um array de structs que, convertido em JSON, possa ajudar no envio para elaborar uma documentação com outra plataforma como o POSTMAN, por exemplo.

O que me indigna é a falta de suporte para parâmetros enviados pelo body que são colhidos a partir da função GetHTTPRequestData(). Essa falta de suporte dificulta na inclusão do tal parâmetro à documentação.

Outro ponto que descobri é a impossibilidade da função GET receber dados do body. Se fizer um dump do retorno de GetHTTPRequestData(), verá que somente o header aparecerá. Já basta a função GET recusar parâmetros oriundos do Form, o que é óbvio, pois uma página GET só recebe o que vem da query string desde os primórdios do HTTP. Espero que a versão 2021 tenha corrigido esse problema.

Espero ter ajudado. Deus os abençoe!