REST V2 Connector

Back Next

Basic structure of the Swagger and OpenAPI specification file

Swagger is a specification for documenting REST API. It specifies the format to describe REST web services.

REST V2 Connector supports swagger specification 2.0 and OpenAPI 3.0.x to interact with web service applications. When you configure a Rest V2 connection, you can specify the path of the Swagger or OpenAPI file in the

Swagger File Path

property.

The swagger or OpenAPI specification file contains the following details:

metadata of the API

server details

operations

path parameters

query parameters

header fields

request details

response details

Servers

You can specify an array of server URL in the servers section in the OpenAPI specification.

The following example shows how servers are defined in the OpenAPI specification file:

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

You can define servers globally at the path level or for specific operations. However, Rest V2 Connector honors the first server listed in the specification file to connect to the REST endpoint.

Alternatively, if you want to specify the server URL when you create a Rest V2 connection, you can add the host URL in the

Advanced Fields

property in the following format:

hosturl:schemes://host

For example,

hosturl:https://openapiworld.com

The server specified in the connection properties takes precedence over the server specified in the specification file.

For more information on creating a Rest V2 connection, see Rest V2 connection properties.

You can't specify variables in a server URL.

In the swagger specification, you can define a server URL using the host keyword. You cannot define multiple servers in the swagger specification file.

The following example shows how servers are defined in the swagger specification file:

{
  "host": "petstore.swagger.io",
  "basePath": "/v2",  
		"schemes": [    
		"https"  
]
}

Parameters

In the OpenAPI specification, you can define parameters at the path level and for specific operations. The parameters at the path level are applicable to all operations defined under the path. The parameters at the operation level are applicable only to the operations under which it is defined.

If the same parameters are defined at the path level and operation level, the operation level parameters take precedence.

You can define the following parameter types:

path parameters

query parameters

header parameters

cookie parameters

The following example shows how the parameters are defined in the OpenAPI specification file:

"paths": {
"/pet": {
"put": {
	"tags": [
	"pet"
],
"summary": "Update an existing pet",
	"description": "Update an existing pet by Id",
	"operationId": "updatePet",
	"parameters": [
{
"name": "status",
"in": "query",
"description": "Status values that need to be considered for filter",
"required": false,
"explode": true,
"schema": {
		"type": "string",
		"default": "available",
		}
	}
]

Ensure that the parameters section in the OpenAPI specification contains the schema type.

In the swagger specification file, you can define parameters for each operation.

The following example shows how parameters are defined in the swagger specification file:

"parameters": [
{
 "in": "body",
 "name": "user",
 "description": "The user to create.",
 "schema": {
  "$ref": "#/definitions/User"
   }          
		}        
]

Request body

Request body defines the structure of the endpoint request body.

In the OpenAPI specification file, you can define parameters and requestBody to connect to a REST endpoint.

The following example shows how the requestBody is defined in the OpenAPI specification file:

"operationId": "addPet",
"requestBody": {
 "description": "Create a new pet in the store",
 "content": {
  "application/json": {
   "schema": {
   "$ref": "#/components/schemas/Pet"
    }
   },
"application/xml": {
 "schema": {
 "$ref": "#/components/schemas/Pet"
   }
  }
 }
}

In the swagger specification file, you can define the parameters section to send a request to the REST endpoint.

The following example shows how the request body is defined in the swagger specification file:

{
"paths": {
	"/users": {
			"post": {
			"summary": "Creates a new user.",
			"consumes": [
			"application/json"
],
			"parameters": [
			{
			"in": "body",
			"name": "user",
			"description": "The user to create.",
			"schema": {
				"$ref": "#/definitions/User"
					} 
		}
]

Response body

Response body defines the response fields of the endpoint. Rest V2 Connector supports only the successful response with HTTP status code 200. For all responses other than status code 200, the field mapping displays a static field named Response_Port.

The following example shows the response body section in the OpenAPI specification file:

"responses": {
"200": {
 "description": "Successful operation",
 "content": {
 "application/xml": {
  "schema": {
   "$ref": "#/components/schemas/Pet"
     }
    },
 "application/json": {
  "schema": {
    "$ref": "#/components/schemas/Pet"
    	}
    }
   }
  }
}

The following example shows the response body section in the swagger specification file:

"responses": {
"200": {
	"description": "A User object",
	"schema": {
	"$ref": "#/definitions/User"
		}
	}
}

Rename Saved Search

Table of Contents

REST V2 Connector

REST V2 Connector

Basic structure of the Swagger and OpenAPI specification file

Basic structure of the Swagger and OpenAPI specification file

Servers

Parameters

Request body

Response body