Histórico da Página
...
Para elucidar a utilização da API Totvs-Rest segue um exemplo de como realizar as chamadas que, por usa vez utiliza o 'SWAGGER
' para gerar a documentação. Assim o exemplo seguirá sempre o padrão: Bloco 'SWAGGER
' seguido de bloco 'PROGRESS
', nesta sequência.
O SWAGGER é uma das principais ferramentas utilizadas para modelagem, documentação e geração de código para APIs do estilo REST
. Com ele é possível especificar a descrição de contratos de APIs REST
. Para o exemplo prático foi utilizada uma simulação de "Manipulação de Pedidos". Segue abaixo os blocos de códigos documentados:
...
No bloco de código (progress) abaixo, então, existe um bloco para documentação do 'SWAGGER', onde são apresentadas informações principais da aplicação como a descrição da mesma com seu Título e versão e, a URL Base da aplicação.
Inicialmente é informada a versão do Swagger
, na própria seção 'swagger'. Na seção 'info' estão as informações da descrição (description
), a versão da API (version
) e o título (title
).
Na seção basePath
colocamos o contexto da aplicação.
Na seção tags
se nomeia o serviço (name
), a descrição do serviço (description
) e os documentos externos (externaldocs
), caso existam, com a descrição e o link de acesso (url
).
Em seguida as chamadas das includes progress progress
referente a padronização das ações dos métodos HTTP
.
Bloco de código | ||
---|---|---|
| ||
/* **SWAGGER** swagger: "2.0" info: description: "Este é um exemplo de aplicação de API no modelo Totvs-rest para um modelo de negocio referente a 'Pedidos'" version: "1.0.0" title: "Exemplo API Totvs-REST" basePath: "/pdp/v1/" tags: - name: "servicoConsultaPedido" description: "Exemplo de grupo de chamada para modelo de negócio 'Pedido'" externalDocs: description: "Mais informações em:" url: "http://tdn.totvs.com" **END SWAGGER** */ {utp/ut-api.i} {utp/ut-api-action.i pi-get GET /~* } {utp/ut-api-action.i pi-send GET /~*/SEND by=email,address=~* } {utp/ut-api-action.i pi-post POST /~* oi=1} {utp/ut-api-action.i pi-put PUT /~* } {utp/ut-api-action.i pi-delete DELETE /~* } {utp/ut-api-notfound.i} |
...
A seguir a documentação referente ao método GET para listar os pedidos existentes. A documentação informa que o recuros acessado será "pedido".
Dentro da seção get
estão contidas todas a sub seções que compõem a modelagem do recurso desse método (podem haver mais recursos). Assim sendo, na seção tags
está definido o path do recurso 'pedido' para montagem da URI: .../pdp/v1/pedido.
Ao enviar a requisição pode-se informar, como parâmentros, filtros do status do pedido.
...