Create a plugin from openapi files
3 minute read
Introduction
In this tutorial, you will learn how to bundle OpenAPI specifications (aka Swagger, and OAS), into plugins so that they may be used as dependencies in API Builder applications to orchestrate data between existing services via flow-nodes.
Prerequisites
- API Builder CLI: All commands on this page require installation of the API Builder CLI as described in the Getting Started With API Builder .
- API Builder project: An API Builder project is required to install and test your new flow-node.
You can use an existing project, or initialize a new one with the following instructions:
// Create a new API Builder project
axway builder init example-project
cd example-project
Creating a new API Builder plugin to bundle OpenAPI specifications
Creating an new plugin to bundle OpenAPI specification files is similar to Creating a standard flow-node plugin, but the difference is you use a --type=oas argument.
// Create a new OpenAPI flow-node plugin
axway builder plugin init --type=oas petstore
cd api-builder-plugin-petstore
The CLI will create your plugin in a new directory called `./api-builder-plugin-petstore` and will install the dependencies for you. The new plugin has the following contents:
// File contents of the OpenAPI plugin
├── package.json
├── openapi/
├── README.md
└─┬ test/
└── test.js
| File Name | Description |
|---|---|
| package.json | This is your module package description file. You should modify it to suit your module. The file is used by npm. See here for more details. |
| openapi/ | This directory is initially empty. You need to place one or more OpenAPI specification files and optionally, a related icon file in this directory. |
| test/test.js | A mocha test suite. You should ensure all of your actions are adequately tested. |
| README.md | A README.md file that you should update with details about your plugin before publishing. It should contain details about how to install it, and the functionality it provides. |
Install your OpenAPI file(s)
After initializing your new plugin, you need to populate it with one or more OpenAPI specification files, by copying them into the ./openapi directory.
cd api-builder-plugin-petstore
cp ~/Downloads/petstore.yaml ./openapi
Install optional icon file(s)
You can also optionally install an icon to use when the flow-node is displayed in the Flow editor. The icon file must have the same root name as your OpenAPI specification file (e.g. “petstore.json” and “petstore.svg”), and can be any one of the supported image formats: bmp, jpeg, png, gif, tiff, or svg. For best results, use svg and keep the icon small and symmetrical (e.g. 50 x 50 pixels).
Testing your plugin
After adding your OpenAPI specification files, run “npm test” to ensure that they are valid. If they are not valid, then you cannot use the specification as-is in API Builder without first correcting the issue(s). You should notify the owners of the specification so that they can correct the issue.
npm test
If all tests pass, then the plugin is ready to be used in API Builder or published.
Using your new plugin in API Builder
Once you have your plugin working and the unit-tests pass, then you can install plugin into an existing API Builder project. If using the parent directory, as suggested at the start of this tutorial, then go to your project directory and install the plugin:
// Install your plugin and start API Builder
cd ..
npm install ./api-builder-plugin-petstore
npm start
You will find your new OpenAPI plugin as a flow-node available in the Flow editor.
Note that this process creates an npm link to your plugin in your package.json file. You may or may not want this, depending on how you want to publish your plugin. To make your plugin re-usable, please refer to the @axway/api-builder-sdk README section on Using the plugin.
For more information, see https://www.npmjs.com/package/@axway/api-builder-oas-flow-node