@axway/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

1. Follow the Getting Started Guide to learn how to install and create API Builder application.

2. Then make sure you have the plugin installed within your application with:

npm install --no-optional @axway/api-builder-plugin-fn-swagger

How to use the plugin?

1. 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.

2. Place your swagger JSON files into the ./swagger folder.

3. (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

4. 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.

5. 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.

Authorization

Authorization parameters described by each flow-node are supplied via the flow editor.

How to configure the plugin?

The first time a new Swagger file is detected, a new configuration file is generated with the name of the Swagger file. For example, if you installed "petstore.json", the plugin will generate conf/petstore.default.js. You can configure the plugin using the configuration options below.

Configuration options

Option	Type	Required	Compatibility	Description
proxy	String	optional	OAS2, OAS3	The URL to use for outbound proxy requests.
insecureSSL	Boolean	optional	OAS2, OAS3	Enables insecure SSL on outbound requests.
uri	Object	optional	OAS2	Contains overrides for the server URI.
uri.protocol	String	optional	OAS2	Overrides the server's protocol, one of: "http", or "https".
uri.host	String	optional	OAS2	Overrides the server's hostname.
uri.port	Number	optional	OAS2	Overrides the server's port (default depends on uri.protocol).
uri.basePath	String	optional	OAS2	Overrides the server's basePath. Should start with a leading slash, unless providing an empty string to remove an existing basePath.

Known limitations

The plugin has the following known limitations:

• #6187: Does not support OAS3 semantic validation on startup
• #6187: Does not support OAS3 wildcard content media-type objects
• #6187: Does not support OAS2 collectionFormat
• #6187: Does not support OAS3 parameter styles
• #6187: Does not support OAS3 parameter explode
• #6187: Does not support OAS3 multipart encoding object
• #6228: Fixes schema references to definitions as they were incorrectly stripping characters.
• #6187: Does not support OAS3 parameter nullable
• #6187: Does not support OAS3 cookie parameters of type object or array
• #6187: Does not support OAS3 parameter allowEmptyValue or OAS2 parameter allowEmptyValue
• #6187: Does not support OAS3 parameter allowEmptyValue or OAS2 parameter allowEmptyValue
• #6276: Does not support OAS3 security schemes of type openIdConnect, or type http with any scheme other than basic.

Changes

4.2.1

• #7600: Fix @axway/requester explicit dependencies.

4.2.0

• #7599: Update @axway/requester.

4.1.0

• #7595: Update @axway/requester dependency.

4.0.2

• #7538: Fixed an issue where the request content-length header was calculated incorrectly when the request body was a string that contains multi-byte characters.

4.0.1

• #7517: Update @axway/api-builder-oas-flow-node dependency.

4.0.0

• #6089: Breaking change: requires minimum Node.js version 16.x.

3.2.9

• #7538: Fixed an issue where the request content-length header was calculated incorrectly when the request body was a string that contains multi-byte characters.

3.2.8

• #7470: Update @axway/api-builder-test-utils devDependency.

3.2.7

• #7495: Updated README.md.

3.2.6

• #7466: Update @axway/api-builder-oas-flow-node dependency.

3.2.5

• #7474: Internal dev-dependency move.

3.2.4

• #7412: Pin in-house dependencies.

3.2.3

• #7411: Internal bump.

3.2.2

• #7403: Update @axway/api-builder-oas-flow-node dependency.

3.2.1

• #7345: Update @axway/api-builder-oas-flow-node dependency.

3.2.0

• #6933: Replace peerDependency on @axway/api-builder-runtime with engines.apibuilder.

3.1.3

• #7139: Update @axway/api-builder-oas-flow-node dependency.

3.1.2

• #7284: Update @axway/api-builder-oas-flow-node dependency.

3.1.1

• #7303: Update @axway/api-builder-oas-flow-node dependency.

3.1.0

• #7282: Update @axway/api-builder-oas-flow-node dependency.

3.0.10

• #7111: Internal refactoring.

3.0.9

• #7155: Update @axway/api-builder-oas-flow-node dependency.
• #7155: Fixed issue with CVE-2021-3918 and removed the dependency on the request library.
• #7155: Fixed an issue where the 'Authorization' header could not be unset (i.e. it was set to null in the Advanced HTTP Options).

3.0.8

• #7123: Update @axway/api-builder-oas-flow-node dependency.

3.0.7

• #7143: Internal unit-test update.

3.0.6

• #7132: Update @axway/api-builder-oas-flow-node dependency.

3.0.5

• #7105: In @axway/requester, response body is no longer logged at DEBUG level to improve performance.

3.0.4

• #7059: Fixes problem loading OAS spec with the error "Cannot convert undefined or null to object".

3.0.3

• #7057: Updated documentation links.

3.0.2

• #7008: Bumped @axway/api-builder-project-utils dependency.

3.0.1

• #6295: Ensured Server URL parameter of generated Flow-node(s) is editable.

3.0.0

• #5352: Breaking change: updated required minimum version of @axway/api-builder-runtime to Utrecht (4.69.0).
• #5352: Updated to use a new version of @axway/api-builder-oas-flow-node, that added support for OAuth2 Client Credentials.

2.9.6

• #7010: OAS methods that describe binary input { type: 'string', format: 'binary' } will now generate parameter schema of type any (i.e. {}) instead of { type: 'string' }.

2.9.5

• #6934: Internal refactoring around code style.

2.9.4

• #6938: Update @axway/api-builder-oas-flow-node dependency to resolve security issue with z-schema.

2.9.3

• #6783: Update @axway/api-builder-oas-flow-node dependency.

2.9.2

• #6732: Fixes No @axway/api-builder-runtime instance error when running OAS plugin tests from a sub-directory of an API Builder project.

2.9.1

• #6546: Update @axway/api-builder-oas-flow-node dependency.

2.9.0

• #6296: Added optional Advanced HTTP Options Headers parameter to generated flow-nodes. This allows overriding headers, as well as defining any headers not in the OAS spec.

2.8.0

• #6549: Fix regression from 2.7.0 where basePath could not be overridden in config for OAS2 definitions.
• #6549: Allow an existing basePath to be removed as part of an override in config for OAS2 definitions by providing the value as an empty string.
• #6412: Added custom HTTP headers to generated flow-nodes.

2.7.8

• #4567: Added api-builder-project-utils to handle automatic swagger directory creation in a project when installing this plugin.

2.7.7

• #6397: Fix integration tests to fail with non-zero exit code.
• #6397: Fix unit test assertions which were not being called.

2.7.6

• #6411: Fix failing unit-tests.

2.7.5

• #6412: Updated to use a new version of @axway/api-builder-oas-flow-node that works with @axway/api-builder-sdk@1.0.0.

2.7.4

• #6322: Previously, references to schema definitions/components that had keys containing URI reserved characters (RFC-3986 section 2.2) (e.g. "Pet!") would be incorrectly encoded, causing a runtime error, "MissingRefError: can't resolve reference schema:///...". Now, references are correctly encoded.

2.7.3

• #6320: Fixed Uncaught Exception Unable to register flow-node on API Builder startup when handling OAS2 definitions with response schemas that were type: "file".

2.7.2

• #6318: Fixes unused references warning.
• #6315: Internal chore.

2.7.1

• #6233: Fix install configuration banner when console width is undefined.

2.7.0

• #6187: Supports OAS3.
• #6265: Now uses the actual service directory, instead of process.cwd(), when loading OAS files and generating config. (requires @axway/api-builder-runtime 4.26.0)
• #6187: Supports OAS3 schema validation on startup
• #6256: Supports loading external OAS definitions from file or URL.
• #6273: Previously, methods that had file inputs would allow the types selector, object, but there is no way of providing a valid file as a JSON object. Now, you can chose from selector for files and streams, and string for raw binary data.

2.6.12

• #6116: Internal cleanup chore.

2.6.11

• #6114: Refactor code for style, security and performance improvements.

2.6.10

• #6115: Internal fix for Sonar scans.

2.6.9

• #6074: Internal CI chore.

2.6.8

• #5764: Modified request and response logging from debug to trace level.
• #5764: Update @axway/requester version to 4.0.0 which provides more accurate logging of data after making modifications before making the request.

2.6.7

• #5711: Internal cleanup of npm scripts.

2.6.6

• #5713: Update nodehandler-utils dependency.

2.6.5

• #5708: Internal changes to update mocha configuration

2.6.4

• #5709: Internal changes to update eslint rules.

2.6.3

• #5707: Internal cleanup to code coverage during build process.

2.6.2

• #5742: Internal change to remove dot dependency for internal config generation.

2.6.1

• #5552: Fix for wrong URI creation in cases when basePath is not specified in Swagger document.

2.6.0

• #5653: Add support for circular references 

2.5.1

• #5622: Fix regression introduced in 2.4.1 where the format of the data returned would change depending on the value of the response rather than just the content-type header. Now, when content type is "application/json" and "Decode Response" parameter is set to "auto", a JSON value will be returned, otherwise it will throw an error while parsing. For other known text-like content-types including "application/xml", a valid string will always be returned. For every other case, a Buffer will be consistently returned.

2.5.0

• #5630: Add support for multipart/form-data in Content Type parameter. multipart/form-data will be prioritized as a default value if the Swagger method has formData fields of type file.
• #5630: Add an enum property choice of application/wwww-form-urlencoded and multipart/form-data to Content Type parameters when Swagger method has formData parameters which are not type file and do not define consumes.
• #5630: Change the default value for Content Type parameters to application/wwww-form-urlencoded, falling back to multipart/form-data and then the first consumes value when either values exist inside the Swagger method's consumes.
• #5640: Fix issue where charset is stripped from the default value for Content Type parameters in some cases.

2.4.1

• #5622: Fixed error when the value of Accept was a derivative of "application/json" and 0 length response body was returned.

2.4.0

• #5329: Support requests using formData parameters with application/x-www-form-urlencoded content type.

2.3.0

• #5432: Swagger plugin adds support for Content-Type, Accept, and Decode Response parameters as "Advanced HTTP Options" on the corresponding Swagger Flow-node, enabling developers to choose the appropriate media-types, and to control how response is decoded when communicating to backend services.

2.2.0

• #5459: Swagger plugin now supports YAML.

2.1.5

• #5488: Swagger plugin is no longer apply swagger validation with swagger-tools package

2.1.4

• #5413: Swagger plugin will now fail on loading Swagger files with semantic validation problems

2.1.0

• #5364: Support insecure SSL option on outbound requests insecureSSL.
• #5414: Prevent logging circular JSON references on error.

2.0.5

• #5359: Log to the console to notify the user whenever configuration files are created on load.

2.0.4

• #5360: No longer fail to load plugin when unsupported or invalid security definitions are defined in a provided swagger document. An error is now logged with the details instead.

2.0.3

• #5392: Removed config from request log data and now only log specific request configuration options such as proxy.

2.0.2

• #5395: Refactored tests.

2.0.1

• #5349: Remove dependency on the enableAuthorizationInFlows preview flag.

2.0.0

WARNING: Installing this release can cause your application to emit a MISSING_KEY error(s) on startup and cause flows to be uneditable in the UI. If you encounter this issue, please contact Axway Support ([e-mail]) so that we may assist you with your upgrade.

• #5384: Breaking Change: Previously, Swagger responses were mapped to outputs having statusCode property which was inconsistent with the rest of the product. Now, responses are mapped to outputs having status property.

• #5073: Requests and responses to external Swagger services are now logged in detail.

• #5349: Breaking Change: Minimum supported version of API Builder is now Jakarta, which supports flow-nodes that advertise authentication parameters.

• #5314: Support generation of stub credentials from new Swagger documents loaded by the plugin.

• #5007: Breaking Change: Previously, there was no validation of the Swagger documents loaded by the plugin when the service was started. Now, the Swagger documents are validated and, if any are invalid, the loading of the plugin is aborted.

• #4919: Breaking Change: The configuration parameter x-vendor-openapi-uri has been renamed to uri.

• #4919: Replace superagent with request for http communication.

• #4918: Breaking Change: Previously, if a request to a method which documented an optional query parameter with a default value and was not supplied to the request, the default value would be sent to the service instead. Now, default values are not used when sending query parameters.

• #4918: Breaking Change: Removed support for the following credential configuration values. Authorization parameters should be provided in the flow editor instead:

  • x-vendor-openapi-username
  • x-vendor-openapi-password
  • x-vendor-openapi-key
  • x-vendor-openapi-token

• #5358: Breaking Change: Headers returned from service are no longer modified by us in the following cases:

  • Headers not defined by the Swagger are no longer removed from the output.
  • The case of header keys are not modified to match the Swagger definition.
  • Headers defined by the Swagger but not in the service response will not be output as undefined.

• #5358: Breaking Change: A Default output is created for all flow-nodes regardless of the Swagger definition.

• #5358: Breaking Change: An Error output is created for all flow-nodes to allow routing on connection errors.

• #5358: The default JSONPath selector for all outputs is now $.response. Only the Error output defaults to $.error.

1.1.1

• #5177: Previously, Swagger plugin was taking specific configurations for all the available services in Swagger folder. Now, it takes optional proxy as additional parameter which is used for tunneling http/s requests through proxy server.

1.0.19

• #5235: Previously, when an error occurred while loading multiple Swagger documents, the filename displayed in the error may refer to the wrong Swagger document. Now the correct file name is displayed.

1.0.18

• #5116: Previously, when errors occurred on load, only the message was logged. Now, the stack trace is logged as well as the path to the Swagger file which caused the issue (if applicable).

1.0.17

• #5111: Previously, Swagger documents with extensions in the same location as path methods failed to be loaded correctly. Now, extensions will be correctly ignored.

1.0.16

• #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.

1.0.15

• #5050: Updating license text.

1.0.14

• #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.

1.0.12

• #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 behavior would be required parameters not being marked as required in the flow-node. Now, the generated flow-nodes will be generated correctly.

1.0.8

• #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.

1.0.6

• #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.

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; 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.