Histórico da Página

...

Para elucidar a utilização da API Totvs-Rest segue um exemplo de como realizar as chamadas e que 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.

INFO

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. Em seguida as chamadas das includes progress referente a padronização das ações dos métodos HTTP.

...

Bloco de código

language	java

/* **SWAGGER** 
    post:
      tags:
      - "pedido"
      summary: "Cadastro de um novo pedido"
      description: "Envia dados de um novo cadastro de pedido para a base de dados utilizando o método POST"
      operationId: "addPedido"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Parâmetros necessários enviados no 'payload' para adicionar o novo pedido"
        required: true
        schema:
          $ref: "#/definitions/payloadEnvioPedido"
  **END SWAGGER** */             
PROCEDURE pi-post:


    DEF INPUT  PARAM jsonInput  AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    ASSIGN jsonOutput = jsonInput.
END.

PUT

A próxima documentação apresenta o método PUT, quando há necessidade de alteração e/ou atualização de algum registro existente.

...

Bloco de código

language	java

/* **SWAGGER** 
    put:
      tags:
      - "pedido"
      summary: "Atualiza um registro existente de pedido"
      description: "Atualiza os dados de um registro de pedido existente na base de dados utilizando o método Put"
      operationId: "putPedido"
      consumes:
      - "application/json"      
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Parâmetros necessários enviados no 'payload' para atualizar um pedido existente"
        required: true
        schema:
          $ref: "#/definitions/payloadEnvioPedido"
   **END SWAGGER** */          
PROCEDURE pi-put:


    DEF INPUT  PARAM jsonInput  AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    ASSIGN jsonOutput = jsonInput.
END.

DELETE

A documentação para o método DELETE informa que para executar a exclusão de um registro é preciso passar como parâmetro na URI uma chave.

...

Bloco de código

language	java

/* **SWAGGER** 
    delete:
      tags:
      - "pedido"
      summary: "Exclui um pedido existente"
      description: "Realiza a exlusão de um pedido existente na base de dados utilizando o método PUT"
      operationId: "deletePedido"
      produces:
      - "application/json"
      parameters:
      - name: "api_key"
        in: "header"
        required: false
        type: "string"
      - name: "petId"
        in: "path"
        description: "Parâmetros necessários enviados no 'payload' para exlcuir um pedido existente"
        required: true
        type: "integer"
        format: "int64"
    **END SWAGGER** */        
PROCEDURE pi-delete:


    DEF INPUT  PARAM jsonInput  AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    ASSIGN jsonOutput = jsonInput.
END.

DEFINITIONS

Na documentação existe também a definição do modelo de dados com os objetos, assim sendo, no exemplo abaixo, foram definidos obejtos payload para envio e retorno de pedidos.

Dentro de cada objeto foi estabelecido o tipo e as propriedades pertinentes a cada um.

Bloco de código

language	java

/* **SWAGGER** 
definitions:
  payloadEnvioPedido:
    type: "object"
    required:
    - "numeroPedido"
    - "codigoCliente"
    properties:
      id:
        type: "integer"
        format: "int64"
      numeroPedido:
        type: "integer"
        example: "ped123456879"
        format: "int64"
      codigoCliente:
        type: "string"
        description: "cliente1234"
      descricaoCliente:
        type: "string"
        example: "Cliente de Teste"
  payloadDeRetornoPedido:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      numeroPedido:
        type: "integer"
        example: "ped123456879"
        format: "int64"
      statusDoPedido:
        type: "string"
        description: "Pedido Aprovado"
        enum:
        - "Aprovado"
        - "Reprovado"      
**END SWAGGER** */

Árvore de páginas

Versões comparadas

Versão antiga 4

Nova versão 5

Chave

INFO

PUT

DELETE

DEFINITIONS