Swagger Editor

The Swagger editor is used to edit the API design making use of YAML or JSON structure. Access to the editor is located on API cards, on the API Catalog page, and its icon is the official Swagger logo:

swagger editor
If you try to access the Swagger editor by any path other than by clicking the icon (for example, if you open more than one tab or window in the browser), it will lead to a malfunction of the editor.

Error scenario:

Editor A and B display the same API. The user makes changes using editor A and saves the information successfully; subsequently, the same user makes changes on editor B. As a result, the API information will be overwritten.

The host defined in the editor does not impact the API register on the Manager, that is, it only concerns the Swagger file; the rest of the content is the same as the API. The API registry supports multiple URLs, both for production and for sandbox, and so the hosts are treated independently.

swagger editor view

When you are editing the API design, the editor monitors possible mistakes according to Swagger’s standard structure and shows them on the preview pane, on the right half of the screen.

The image below is shows an error message related to the host: it doesn’t have a base path (the right thing would be adding a value, such as /ecommerce/v1. If you have doubts about the Swagger specification, access this page).

swaggerEditor errorMsg

The editor contains all information related to the API. When the data are saved, the Manager stores the content of the editor and updates the basic resources and operations data on the system.

The Swagger editor allows you to download the Swagger file, generate a server and generate client.

Download the Swagger file

You can download the API Swagger file in two formats: YAML or JSON. To do so, click the File button and choose Save as YAML or Convert and save as JSON.

swagger download

Server Generation

In Generate Server, you can generate the basic structure of a server for exposing the API.

SwaggerEditor generateServer

Client/SDK generation

In Generate Client, you can generate a client in several languages to consume API resources, thus accelerating the development process.

SwaggerEditor generateServer

After saving the Swagger, the user is redirected to the success screen on the Manager, where it’s possible to create a plan or download the Swagger file of the API.

Remember that the Swagger download hosts on the Manager and on the Swagger editor are not connected, unless the same domain is registered in both places.

If there’s an error when saving the API, a warning will pop up on the editor’s preview pane. In the image below, for example, the error message was generated because a resource registered on the Manager was lacking in the Swagger file.

swaggerEditor saveError
Thanks for your feedback!

Share your suggestions with us!
Click here and then [+ Submit idea]