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:

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.

Editing the API

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.

If there are any errors, the SAVE and SAVE AS NEW REVISION buttons will be disabled, which means that it will not be possible to save the changes until the indicated errors have been corrected.

The image below 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 "/petstore/v3". If you have doubts about the Swagger specification, access this page).

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 also allows you to download the Swagger file, generate a server, and generate a client.

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.

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.

Saving the changes

There are two options for saving changes made in the editor, which are located at the top right corner of the screen:

SAVE: allows you to save the changes made by overwriting the current revision of the API, i.e. without generating a new revision.
SAVE AS NEW REVISION: saves the changes by creating a new revision for the API.

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.

Be careful when saving changes to the same revision. If there is any error in the change, an API deployed in production could be negatively impacted, resulting in failures or service interruptions. Make sure to carefully review all changes before saving them to the same revision.
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.

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.

Server Generation

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

Client/SDK generation

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

Thanks for your feedback!

EDIT

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