How to generate and use commands from an OpenApi endpoint
1. OpenApi repositories in the Workflow Executor
OpenApi, formerly/also known as Swagger, is a specification used for building APIs.
It is usually used to define your APIs to others, but in our case you can use it to define commands!
The practical thing about the OpenApi repositories is that all the implementation is already defined within the specification.
There is no need to implement any further logic, everything that is needed for the commands is defined within the API.
In this guide we will work with the example of the Petstore.
1.1. Adding a predefined OpenApi repository
To add a repository from an OpenApi endpoint, you only need to provide the link to the Swagger Json and give it a name.
If the OpenApi requests authorisation, you have the possibility to save your login data here, for a more convenient access.
1.2. Using commands from an OpenApi repository
Commands from the OpenApi repositories can expect input in one of two forms:
-
Normal Parameters: You can use the commands just like any other command, you do not have to pay attention to anything special.
Simply enter the desired data!
Figure 3. A command with normal Parameters -
Request Bodies: Sometimes the command demands a http request body as an input value.
In that case your input needs to match the structure defined in the corresponding schema,
as the input will be put into the http request directly, without editing or adapting it before.
Figure 4. A command with a requestBody as input
2. Defining your own OpenApi repository
This guide will not cover how to set up a whole Swagger Specification, a guide for that can be found here.
For now, we will only focus on how commands are defined.
2.1. Using the Http Request Body as Input-Variables
Let’s look at the first command: Update an existing Pet
/pet:
put:
tags:
- pet
summary: Update an existing pet (1)
description: Update an existing pet by Id (1)
operationId: updatePet
requestBody: (2)
description: Update an existent pet in the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'200':
description: Successful operation
content:
application/xml:
schema:
$ref: '#/components/schemas/Pet'
application/json:
schema:
$ref: '#/components/schemas/Pet'
'400':
description: Invalid ID supplied
'404':
description: Pet not found
'405':
description: Validation exception
security:
- petstore_auth:
- write:pets
- read:pets
| 1 | As you can see, the summary will be the name of the command, the description will be displayed underneath. |
| 2 | The Input-Variable, in this case, is defined as a request body. Therefore, the user of the command has to supply a correctly put together string of a http request body. The schema will describe exactly what the update body should look like. In this case it is a link to the following: |
Pet:
required:
- name
- photoUrls
type: object
properties:
id:
type: integer
format: int64
example: 10
name:
type: string
example: doggie
category:
$ref: '#/components/schemas/Category'
photoUrls:
type: array
xml:
wrapped: true
items:
type: string
xml:
name: photoUrl
tags:
type: array
xml:
wrapped: true
items:
$ref: '#/components/schemas/Tag'
status:
type: string
description: pet status in the store
enum:
- available
- pending
- sold
xml:
name: pet
According to this schema, the http request body (in the command the Input-Variable updatePetBody) has to be similar to:
{
"id": 10,
"name": "doggie",
"category": {
"id": 1,
"name": "Dogs"
},
"photoUrls": [
"string"
],
"tags": [
{
"id": 0,
"name": "string"
}
],
"status": "available"
}
|
It often helps to use the Swagger Editor to get a better understanding of what an OpenApi defines and an overview over the commands. |
2.2. Using Parameters as Input-Variables
Now let’s look at the „Updates a pet in the store with form data“ command:
post:
tags:
- pet
summary: Updates a pet in the store with form data
description: ''
operationId: updatePetWithForm
parameters: (1)
- name: petId
in: path (2)
description: ID of pet that needs to be updated
required: true
schema:
type: integer
format: int64
- name: name
in: query
description: Name of pet that needs to be updated
schema:
type: string
- name: status
in: query
description: Status of pet that needs to be updated
schema:
type: string
responses:
'405':
description: Invalid input
security:
- petstore_auth:
- write:pets
- read:pets
| 1 | The Parameters will be used for the Input-Variables of the command. You can specify a name and type for the variable (if required). |
| 2 | Via „in:“ you can determine where in the http request (the query or the path) the parameter should be put. |