Swagger flow-node

Overview

The Swagger plugin, @axway/api-builder-plugin-fn-swagger, loads Swagger documents from the ./swagger folder in your application and generates one Swagger flow-node per Swagger document. The generated Swagger flow-nodes expose methods that can be used within API Builder flows for communication with the API services described in your Swagger documents.

The Swagger plugin is installed as part of the default API Builder project; however, if you need to manually install it for some reason, navigate to your application folder and execute the following command:

npm install --no-optional @axway/api-builder-plugin-fn-swagger

For additional getting started information, refer to the API Builder Getting Started Guide.

Using the Swagger plugin

During the npm install, the Swagger plugin will create the ./swagger folder in the root directory of your application. If the ./swagger folder already exists, it will be preserved with all of its content. To use the Swagger plugin:

  1. Place your Swagger files (in JSON or YAML format) into the ./swagger folder.
  2. Place your service icons into the ./swagger folder. This is optional but highly recommended to make your flows more readable. The icons must have the same name as the Swagger files for your service. Additionally, the icons must be one of the following file formats: bmp, jpeg, jpg, png, gif, tiff, or svg
  3. Execute npm start to start your application. The Swagger flow-nodes will be available in the Connector section of the flow-node list on the left side of the API Orchestration user interface. You should see a plugin listed for each Swagger file successfully loaded from your ./swagger folder.

For example, here are the nodes for a service that has two Swagger documents, gmail.json and petstore.yaml. For the Gmail Swagger, we have included a PNG icon file. Swagger Petstore is using the default icon. For more information on using the Swagger plugin with Gmail, see Authorization: Access Gmail using Swagger flow-node.

The flow-nodes generated for the Swagger service expose the methods that are defined in that Swagger document. For example, here we have imported a Swagger for Gmail, and the available methods are the APIs that the Swagger document describes.

The methods in the flow-nodes generated by the Swagger plugin expose all the parameters defined in the Swagger document, their descriptions, and the schema definitions. 

 

 

Here we have three outputs. All flow-nodes generated by the Swagger plugin will have at least Default and Error outputs, with more being available if the provided Swagger document advertises additional known status codes. In this case, the Swagger document advertises a known 200 status code for the API corresponding to the gmail.users.messages.get method.

When executing the flow-node, if the Gmail service responds with a 200 status code, the 200 output will be triggered. In the case that the service responded with any other status code, a Default will be triggered allowing for alternative routing and inspection of the response data.

An Error will be triggered if the flow-node fails to make a request, for example, due to a timeout, or an internal error occurs.

Each output will describe the type of response data and a more complex schema of the expected object structure. In this case, 200 and Default both return a structure containing status, headers, and data. The Error contains message and stack allowing for the error to be identified and tracked.

Authorization

As well as parameters, the Swagger document describes the Authorization requirements of an API. If a Swagger flow-node requires authorization, the flow-node will expose that authorization as a parameter to allow you to set the credential to use. For more information on how authorization is defined in Swagger, see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-requirement-object.

The Swagger flow-node supports API Key, HTTP Basic, and OAuth 2.0 credentials.

For example, this Swagger document is defining an OAuth 2.0 security definition in the section securityDefinitions which it is named Oauth2. Subsequently, in the method definitions, the Oauth2 security definition is specified as a requirement.

swagger/gmail.json  Expand source
...
  "securityDefinitions": {
    "Oauth2": {
      "authorizationUrl": "https://accounts.google.com/o/oauth2/auth",
      "tokenUrl": "https://accounts.google.com/o/oauth2/token",
      "description": "Oauth 2.0 authentication",
      "flow": "accessCode",
      "scopes": {
        "https://mail.google.com/": "Read, send, delete, and manage your email",
        "https://www.googleapis.com/auth/gmail.compose": "Manage drafts and send emails",
        "https://www.googleapis.com/auth/gmail.insert": "Insert mail into your mailbox",
        "https://www.googleapis.com/auth/gmail.labels": "Manage mailbox labels",
        "https://www.googleapis.com/auth/gmail.metadata": "View your email message metadata such as labels and headers, but not the email body",
        "https://www.googleapis.com/auth/gmail.modify": "View and modify but not delete your email",
        "https://www.googleapis.com/auth/gmail.readonly": "View your email messages and settings",
        "https://www.googleapis.com/auth/gmail.send": "Send email on your behalf",
        "https://www.googleapis.com/auth/gmail.settings.basic": "Manage your basic mail settings",
        "https://www.googleapis.com/auth/gmail.settings.sharing": "Manage your sensitive mail settings, including who can manage your mail"
      },
      "type": "oauth2"
    }
  },
...
  "paths": {
...
    "/{userId}/messages/{id}": {
      "get": {
        "operationId": "gmail.users.messages.get",
        "security": [
          { "Oauth2": [ "https://mail.google.com/" ] },
          { "Oauth2": [ "https://www.googleapis.com/auth/gmail.metadata" ] },
          { "Oauth2": [ "https://www.googleapis.com/auth/gmail.modify" ] },
          { "Oauth2": [ "https://www.googleapis.com/auth/gmail.readonly" ] }
        ],
        ...
    },
...
  }
...
  

The flow node in API Builder reflects this as an authorization parameter named Oauth2 in the parameters panel:

This parameter can be a Selector, a String, or a Credential. The Selector and String options allow you to get the credential from an external source, for example, the credential could be read from a header on the incoming request or it could be read from some external vault or database. The Credential option tells API Builder to read the credential from its internal credential store. 

To simplify populating the credential store with suitable credentials, the Swagger plugin will automatically generate stub credentials when loading new Swagger documents. For more information, see Authorization in Swagger Plugin. For more information on credentials, see API Builder Credentials.

Configure the Swagger plugin

In some scenarios, you may need to override the information in the Swagger document. For example, to connect to staging servers rather than production ones while in testing. 

When a new Swagger document is loaded a default configuration file is created for it in the conf folder of your project.

conf/gmail.default.js  Expand source
module.exports = {
	// The configuration settings for your Swagger service.
	pluginConfig: {
		'@axway/api-builder-plugin-fn-swagger': {
			'gmail': {
				// It is possible to override Swagger URI options when constructing
				// outbound requests from the Swagger plugin.
				uri: {
					// protocol: 'https',
					// host: 'hostname',
					// port: 443,
					// basePath: '/api'
				}
			}
		}
	},
	// The following authorization credentials needed to use the Swagger service.
	// Please follow this guide to manually configure the credentials:
	// https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/authorization.html
	authorization: {
		credentials: {
			'Gmail Oauth2': {
				...
			}
		}
	}
};

  

Configure endpoint URI

You can configure endpoint URI in the generated configuration file for your Swagger. 

To configure the endpoint URI, set the following parameter:

  • uri - If this parameter is set, the plugin module will override the predefined endpoint URI.

Additionally, you can set the port, host, protocol, and base path as described in the following table.

Configuration parameters Description
uri.protocol The application protocol to use. For example: http or https
uri.host The server name.
uri.port The port on which the host system listens for requests. This parameter is optional. If a port is not specified, the default port will be set depending on the protocol.
uri.basePath The path to the API.

Accept and Content-Type

Starting from version 2.3.0 the Swagger plugin respects the `consumes` and `produces` properties in Swagger documents. It is parsing this information and generates Advanced HTTP Options based on it.

More specifically:

  • Content-Type is created based on the information in "consumes". This parameter is only available for methods that have a body or formData payload.
  • Accept is created based on the information in "produces".

Selecting default mime-type

Here are some rules regarding how the system chooses the mime-type that will be set to Content-Type and Accept headers as part of the underlying HTTP request:

For Accept (always) and for Content-Type where methods have a body payload:

  • If there are no valid mime-types in consumes/produces the default mime-type used is application/json (this is for backward compatibility)
  • If there is only one type specified in the consumes/produces property it is used by default
  • If there are more mime-types the prioritization of selecting the default type is the following order:
    1. application/json
    2. Types ending with +json
    3. The first valid type

For Content-Type where methods have formData parameters:

  • If there are no valid mime-types in consumes:
    • If the method has file parameters, the default mime-type is multipart/form-data
    • If the method does not have file type parameters, the default mime-type is application/x-www-form-urlencoded
  • If there are valid mime-types in consumes:
    • If there are file type parameters, use multipart/form-data if it exists; otherwise, use application/x-www-form-urlencoded or the first valid type
    • If there are no file type parameters, use application/x-www-form-urlencoded if it exists; otherwise, use multipart/form-data or the first valid type

Overriding the default selection

The system offers the possibility to override the default selection.

If there are types specified in Swagger the user can select the desired type from the drop-down:

If there is no consumes/produces information specified in Swagger, the system shows an input field rather than a drop-down, and the user can specify the value that they want to use:

Icon

Although version 2.3.0 introduces more flexibility in respect to content types it still does not allow to completely skip sending the Content-Type and Accept HTTP headers. This is a known issue and will be fixed in a future version of the plugin.

Filtering invalid types

According to RFC-7321, the " Internet media types ought to be registered with IANA according to the procedures defined in ..."  - So, if the Swagger document contains invalid content types, the system will filter those types and will not show them in the UI. A package called content-type is used under the hood to verify the validity of the content type. It does not check if the type is registered in the IANA registry but check about the validity of its name. In other words, a type named 'application/jsonsssss' will not be filtered but a type called 'banana' will be filtered and not shown in the UI.

Decoding Response

Starting from version 2.3.0 the user has the option to configure the response format. For backward compatibility, by default, the system applies the best effort to decode according to the content types specified. If set to binary Node.js Buffer is returned for further processing in the Flow.

 

Additional information

For how-to information on accessing Gmail using a Swagger flow-node, refer to Access Gmail using a Swagger flow-node.

Related Links