OpenAPI/Swagger Component"

Table of Contents

• General information
  • Description
  • Purpose
  • Completeness Matrix
  • How works. API version/SDK version
• Credentials
  • Type
  • A URL to an OpenAPI/Swagger document
• Actions
  • Make Request
• Known Limitations

General information

Description

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. OpenAPI (Swagger) document needs to be hosted online and should be reached without authentication. You need to provide a URL to this document in the credentials.

Purpose

Using OpenAPI Specification make request to REST API on elastic.io platform.

Completeness Matrix

Completeness Matrix

How works. API version / SDK version

Currently, it is supported OpenAPI version 2.0 documents. It is used Swagger Client version 3.10.0. OpenAPI Specification.

Credentials

Type

Authentication type field to define the authentication schema that would be used for making request. It is supported 4 auth type:

• No Auth - used by default, make request without authentication.
• Basic Auth - make request with basic authentication, Username and Password fields should be specified:

• API Key Auth - make request with API key in headers authentication, Header Name and Header Value fields should be specified:

• OAuth2 - it is supported Authorization code OAuth2 flow. Fields:
  • Client Id - is a public identifier for apps
  • Client Secret - is a secret known only to the application and the authorization server
  • Auth URI - uri for authorization
  • Token URI - uri for getting an access token
  • Scopes - is a scope of the access request

A URL to an OpenAPI/Swagger document

A URL to an OpenAPI/Swagger document that would define the calls that could be made, as example https://petstore.swagger.io/v2/swagger.json

Actions

Make Request

List of Expected Config fields

Path

A dropdown for the paths than defined in the OpenAPI document.

Operation

A dropdown for the operations that are allowed for a previously defined path.

Don't throw Error on Failed Calls

An option as to whether or not errors should be thrown for HTTP codes in the 4xx/5xx range.

NOTE: an exception is the 401 HTTP status code - error would be thrown for this code regardless of field value (true/false)

Expected input metadata

Input metadata is depend on parameters, that are defined in operation: path parameters are defined as a separate fields, and body as object that should be configured by user. For example, path /pet/{petId} and operation get metadata is:

  {
    "type": "object",
    "properties": {
      "petId": {
        "type": "integer",
        "required": true
      }
    }
  }

OpenApi Description for path `/pet/{petId}` and operation `get`

 {
   "paths": {
     "/pet/{petId}": {
       "get": {
         "tags": [
           "pet"
         ],
         "summary": "Find pet by ID",
         "description": "Returns a single pet",
         "operationId": "getPetById",
         "produces": [
           "application/json",
           "application/xml"
         ],
         "parameters": [
           {
             "name": "petId",
             "in": "path",
             "description": "ID of pet to return",
             "required": true,
             "type": "integer",
             "format": "int64"
           }
         ],
         "responses": {
           "200": {
             "description": "successful operation",
             "schema": {
               "$ref": "#/definitions/Pet"
             }
           },
           "400": {
             "description": "Invalid ID supplied"
           },
           "404": {
             "description": "Pet not found"
           }
         },
         "security": [
           {
             "api_key": []
           }
         ]
       }
     }
   }
 }

Expected output metadata

  {
      "type": "object",
      "properties": {
        "headers": {
          "type": "object",
          "properties": {},
          "required": true
        },
        "body": {
          "type": "object",
          "properties": {},
          "required": true
        },
        "responseCode": {
          "type": "number",
          "required": true
        }
      }
    }

Known limitations

• OpenApi v2.0 is supported only
• Multiply hosts are not supported
• Each operation should contains only one tag
• Authentication for access to OpenAPI (Swagger) file is not supported
• OAuth2 authentication type is not supported in real-time flows due to platform limitations