@axway/api-builder-plugin-fn-swagger NPM

api-builder-plugin-fn-swagger

About

This plugin searches for swagger documents in a swagger folder in your application and generates one flow-node per document to be used within Axway API Builder's.

The generated flow-nodes export functions that can be used withing API Builder flows for communication with APIs services described in your swagger documents.

Getting started

Follow the Getting Started Guide to learn how to install and create API Builder application.
Then make sure you have the plugin installed within your application with:

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

How to use the plugin?

During the npm install phase the swagger plugin will create a folder named ./swagger in the root of you application. Note that if the folder already exists it will be preserved with all of its content.
Place your swagger JSON files into the ./swagger
(Optional) Place your service icons into the ./swagger folder. The icon should have the same name as swagger JSON file for your service and should be one of the following formats - bmp | jpeg | jpg | png | gif | tiff | svg
Run your app with npm start and the flow-nodes will be available in the tool panel of your application. In the Connectors section, you should see a plugin listed for each JSON Swagger file successfully loaded from your ./swagger folder.
Each flow-node will have a corresponding number of functions based on what has been described in the swagger JSON specification for particular service. Each of these functions could be used during the flow execution.

How to configure the plugin?

Currently the configuration is related with configuring the authentication and endpoint URI to successfully communicate with the service.

Configure Authentication

Depending on the auth type we need different set of parameters to be specified.

Basic Authentication

For basic authentication the following parameters should be provided:

Config params	Description
'x-vendor-openapi-username'	basic authentication type requires to provide username
'x-vendor-openapi-password'	basic authentication type requires to provide password

API Key Authentication

For api key authentication the following parameters should be provided:

Config params	Description
'x-vendor-openapi-key'	apiKey authentication type requires to provide key

OAuth Authentication

For oAuth authentication the following parameters should be provided:

Config params	Description
'x-vendor-openapi-token'	OAuth authentication type requires to provide token

Optional Parameters Related with Authentication

'x-vendor-openapi-authtype' - This parameter is optional and only needed when the authentication mechanism for the service is ambiguous. Possible values are - basic, apiKey or oauth2.

If this parameter is omitted the application will detect your parameters provided to decide about the authentication strategy that must be applied. If you provide username and password basic authentication will be applied, if you provide apiKey - api key authentication will be applied, if you provide token - oauth2 authentication will be applied.

Configure Endpoint URI

'x-vendor-openapi-uri' - if this parameter is set the module takes it into account to override the predefined endpoint url. One could specify either the port, host, protocol, or base path as descibed in the table bellow:

Config params	Description
'x-vendor-openapi-uri.protocol'	application protocol to use, e.g. either http, or https
'x-vendor-openapi-uri.host'	server name
'x-vendor-openapi-uri.port'	specifies the port on which the host system listens for requests. This parameter is optional. The default one will be set, depends on the protocol.
'x-vendor-openapi-uri.basePath'	basePath is the path to the API

Known Limitations

The plugin has the following known limitations:

If there are invalid swaggers among your files in the ./swagger folder the plugin will fail to load and no flow-nodes will be created
If the user does not configure authentication in accordance to 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
Paths that deals with file upload download are currently not supported

License

This code is proprietary, closed source software licensed to you by Axway. All Rights Reserved. You may not modify Axway’s code without express written permission of Axway. You are licensed to use and distribute your services developed with the use of this software and dependencies, including distributing reasonable and appropriate portions of the Axway code and dependencies. Except as set forth above, this code MUST not be copied or otherwise redistributed without express written permission of Axway. This module is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement (General Conditions) located here: https://support.axway.com/en/auth/general-conditions. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.