Getting information from the Swagger UI docs

Official Content

Let's see an example where we have a RESTful service (in fact it's a Business Component exposed as a Rest service). Suppose that we want to build a consumer for that service.

We've activated the Generate OpenAPI interface property so the default.yaml file is available for us. As we need to implement a consumer, the documentation will help us for that purpose.

Note that the information of the OpenAPI (Swagger) docs can be easily read using the OpenAPI import tool.

However, here we explain how the same process could be done (with a rational analysis effort) using the Swagger UI tool.

Let's start looking at the Product BC structure and properties:

i2016_04_05_20_35_436_png

Note that:

  • Expose as Web Service= TRUE
  • Web Service Protocol= Rest Protocol

We'll concentrate here on the HTTP POST method. In particular for that HTTP verb, the default.yaml file includes the following lines:

/Product/{ProductId}:
post:
      tags:
        - Product
      summary: "Inserts a Product"
      parameters:
        - name: "ProductId"
          in: "path"
          description: "Product Id"
          required: true
          type: "integer"
          format: "int32"
        - name: "Product"
          in: "body"
          description: "SDT of Product"
          required: false
          schema:
            $ref: "#/definitions/Product"
       
      responses:
        200:
          description: "Successful operation"
          schema:
            $ref: "#/definitions/Product_z"
        404:
          description: "Not found"

Graphically, it is represented as follows by the Swagger UI:

i2016_04_05_20_39_257_png

You can click on "Try this operation", and complete the request form that appears, which looks as shown in this example:

i2016_04_05_20_46_589_png

After completing the form you have the following summary of the HTTP Request, where you can get information about the HTTP headers used to execute the HTTP POST verb, and the JSON body format.

Swagger sample Try operation

The JSON Body can be imported in GeneXus using the JSON Import tool (Tools > Application integration), and the correct SDT for that JSON format will be automatically created in the KB.