Swagger flow-node

The api-builder-plugin-fn-swagger plugin searches for Swagger documents in the /swagger folder in your application and generates one Swagger flow-node per Swagger document. The generated Swagger flow-nodes export functions that can be used within API Builder flows for communication with the API services described in your Swagger documents.

Getting started

Beginning with the Canberra release, the api-builder-plugin-fn-swagger plugin is installed as part the API Builder Standalone installation process. To install the Swagger plugin in previous API Builder Standalone releases, navigate to your application folder and execute the following command:

npm install --save @axway/api-builder-plugin-fn-swagger

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

Use 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. The icons should have the same name as the Swagger JSON files for your service. Additionally, the icons should 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.

Configure the Swagger plugin

Currently, you can configure authentication and endpoint URI to successfully communicate with your API services.

Configure authentication

Depending on the authentication type, you need to specify different sets of parameters.

Basic authentication

For basic authentication, the following parameters should be provided:

Configuration parameters Description
x-vendor-openapi-username Basic authentication requires that a username is provided.
x-vendor-openapi-password Basic authentication requires that a password is provided.

API key authentication

For API key authentication, the following parameter should be provided:

Configuration parameter Description
x-vendor-openapi-key API key authentication requires that an API key is provided.

oAuth authentication

For oAuth authentication, the following parameter should be provided:

Configuration parameter Description
x-vendor-openapi-token OAuth authentication requires that a token is provided.

Optional parameter

The following parameter is optional:

  • x-vendor-openapi-authtype - Only needed when the authentication mechanism for the service is ambiguous. Possible values are: basic, apiKey, or oauth2

Configure endpoint URI

To configure the endpoint URI, set the following parameter:

  • x-vendor-openapi-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
x-vendor-openapi-uri.protocol The application protocol to use. For example: http or https
x-vendor-openapi-uri.host The server name.
x-vendor-openapi-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.
x-vendor-openapi-uri.basePath The path to the API.

Known limitations

The Swagger plugin has the following known limitations:

  • If there are invalid Swagger files in your/swagger folder, the plugin will fail to load and no Swagger flow-nodes will be created.
  • If the user does not configure authentication in accordance with what is described in the Swagger file, the service may fail to authenticate against the service.
  • Only one authentication mechanism can be used for all the paths described in the Swagger file for the service.
  • File upload or download paths are currently not supported.

Related Links