Tips on using Stoplight for API Design for API Builder

Tips for using Stoplight for API Design for API Builder

Axway’s API Builder makes it easy to create APIs in minutes with a low-code/no-code interface and a powerful flow engine.

A common starting point for creating APIs is an API description in the form of an OpenAPI specification. Stoplight is a powerful API Design tool for creating OpenAPI specifications.

This post will describe a couple of tips for using Stoplight to create API definitions for API Builder.

OpenAPI 3.0 vs OpenAPI 2.0

You can read about the differences between OpenAPI 2.0 (OAS2) and OpenAPI 3.0 (OAS3) here but the main point of bringing this up is that while Stoplight supports both, it defaults to OAS3.

Furthermore, while API Builder support for OAS3 is currently in the works, it currently only supports OAS2.

Until API Builder supports OAS3, when you create your Stoplight API definition, you should select OAS2 as shown below:

Select OAS2

Note that you can select either JSON or YAML as the format for the API

Remove References

When you design your API in Stoplight, you should be using models and references to models for your endpoint body and response definitions as shown below:


In the screenshot above, you can see that my Get all employees endpoint returns an array of employees defined as a reference to the employee model as follows:


This makes maintaining your API project(s) and collaboration more scalable.

However, when you export your API so that it can be imported into API Builder, you need to dereference these as shown below:

Dereference on Export

Note that you can select either JSON or YAML as the format for the API since API Builder supports both on import.

If you don’t dereference your references (i.e. select Bundled), you will get an error when trying to import the API definition file into API Builder as shown below:


In this blog post, we looked at two tips for using Stoplight for creating API definitions for use with API Builder, namely (a) to use OAS2 when creating your API in Stoplight and (b) select dereferenced for your references on the export of your API in Stoplight.

Learn more about Stoplight and how they are powering the world’s leading API-First companies.


Previous articleExploring digital transformation in the energy industry with Vicki Knott
Next articleAG2R LA MONDIALE provides the best data flow experience to its customers with Axway MFT
Principal Presales Architect II – Leor Brenman has over 12 years’ experience in Enterprise Software and more than 30 years working in the tech industry for companies like Vaultus, Antenna, Appcelerator and Axway. He has a strong technology background and specializes in mobile, API, integration and enterprise applications. Leor has a BS and MS in Electrical Engineering from Rutgers University in NJ, USA.


Please enter your comment!
Please enter your name here