Swagger flow-node

Overview

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

Support for OAS 3 was added in version 2.7.0.

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 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 plugin:

  1. Place your OAS 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 OAS 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 plugin will generate flow-nodes from your OAS specifications and 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 OAS 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 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 OAS document. For example, here we have imported a Swagger for Gmail, and the available methods are the APIs that the OAS document describes.

The methods in the flow-nodes generated by the Swagger plugin expose all the parameters defined in the OAS 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 OAS document advertises additional known status codes. In this case, the OAS 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 OAS 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 flow-node supports API Key, HTTP Basic, and OAuth 2.0 credentials.

For example, this OAS 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 plugin will automatically generate stub credentials when loading new OAS 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 OAS document. For example, to connect to staging servers rather than production ones while in testing. 

When a new OAS 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 the OAS2 flow-node: Gmail
    pluginConfig: {
        '@axway/api-builder-plugin-fn-swagger': {
            'gmail': {
                // It is possible to override URI options when constructing
                // outbound requests to this service.
                uri: {
                    // protocol: 'https',
                    // host: 'hostname',
                    // port: 443,
                    // basePath: '/api'
                }
            }
        }
    },
	// The following authorization credentials needed to use this service.
    // Please follow this guide to manually configure these credentials:
    // https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/api_builder_credentials.html
	authorization: {
		credentials: {
			'Gmail Oauth2': {
				...
			}
		}
	}
};

  

Configure endpoint URI

You can configure endpoint URI in the generated configuration file. 

Note, this only applies to OAS 2 documents. For OAS 3 documents, you can make use of Server parameters defined in the OAS3 document, or provide a custom Server URL within the flow.

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 OAS documents. It is parsing this information and generates Advanced HTTP Options based on it.

More specifically:

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

Selecting default mime-type

Here are some rules regarding how the system chooses the mime-type that will be set to Accept and Content-Type 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

Starting from version 2.7.0, the user can completely skip sending the Accept and Content-Type headers by toggling the respective header and leave the String value empty.

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 OAS 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 Swagger flow-node.

Related Links