This version has been deprecated
This version is no longer supported. Please upgrade to the latest version.
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.
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
./swaggerin 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
(Optional) Place your service icons into the
./swaggerfolder. 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
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.
Depending on the auth type we need different set of parameters to be specified.
For basic authentication the following parameters should be provided:
|'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:
|'x-vendor-openapi-key'||apiKey authentication type requires to provide key|
For oAuth authentication the following parameters should be provided:
|'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:
|'x-vendor-openapi-uri.protocol'||application protocol to use, e.g. either http, or https|
|'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|
The plugin has the following known limitations:
- If there are invalid swaggers among your files in the
./swaggerfolder 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
- #5111: Previously, swagger documents with extensions in the same location as path methods failed to be loaded correctly. Now, extensions will be correctly ignored.
- #5112: Previously, the server start would fail with a schema validation error when attempting to handle swaggers, that didn't contain the "definitions" section. Now, the loading of services with a swagger documents without the "definitions" section is allowed.
- #5050: Updating license text.
- #5004: Previously, the default configuration file generation did not preserve the service name during the creation of the initial service configuration file if the service had its service name manually changed, resulting in generating unique file name every time the service was restarted. Now, the swagger plugin generates configuration files by preserve the service name and stops once a config for the given service is created.
- #4979: Previously, api-builder-plugin-fn-swagger generated incorrect inputs and outputs for flow-nodes when references were used in multiple places in the original swagger document. An example of the incorrect behaviour would be required parameters not being marked as required in the flow-node. Now, the generated flow-nodes will be generated correctly.
- #4897: Previously, api-builder-plugin-fn-swagger failed on loading swagger files that specify parameters with missing "in" property as well as did not dereference schemas from global "parameters" and "responses" sections. Now, swagger files with parameters and responses that just refer to schemas in "parameters" and "responses" section are loaded successfully.
- #4757: Changed SCM repository and associated internal cleanup.
- #4760: Correctly trigger default response. Previously service connectors and flow-nodes generated with api-builder-plugin-fn-swagger did not handle the cases where the swagger definition have default response. Now service connectors and flow-nodes generated with api-builder-plugin-fn-swagger will use the proper response description even when default descriptions exists. For example if the service returns http code 301 and there is no response defined for 301 the "default" response will be used if present in the swagger document.
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; EXCEPT THAT IF YOU RECEIVED A FREE SUBSCRIPTION, LICENSE, OR SUPPORT SUBSCRIPTION FOR THIS CODE, NOTWITHSTANDING THE LANGUAGE OF THE GENERAL CONDITIONS, AXWAY HEREBY DISCLAIMS ALL SUPPORT AND MAINTENANCE OBLIGATIONS, AS WELL AS ALL EXPRESS AND IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED INFRINGEMENT WARRANTIES, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND YOU ACCEPT THE PRODUCT AS-IS AND WITH ALL FAULTS, SOLELY AT YOUR OWN RISK. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.