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 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 JSON files 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 JSON 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.json. 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, Default will be triggered allowing for alternative routing and inspection of the response data.

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 the 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 dataError contains message and stack allowing for the error to be identified and traced.

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, this Oauth2 security definition is specified as a requirement.

swagger/gmail.json
...
  "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
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. default port will be set depending on the protocol.
uri.basePath The path to the API.

Related Links