Visual Editor for OpenAPI Definitions

Using Visual Editor, you can:

• Edit API information: title, description, license, contact information, link to external documentation.

• Edit operation metadata: summary, description, tags.

• Edit servers and server variables in OpenAPI 3.0 definitions.

• Delete operations.

• Manage tags and edit tag metadata.

• Add and delete models.

• Edit model descriptions (only for models in the definitions and components/schemas sections).

To switch to Visual Editor, click  Show Visual Editor in the sidebar of the SwaggerHub editor. If the cursor was inside a specific operation or model in the YAML code, Visual Editor will open for that operation or model.

You cannot switch to Visual Editor if the definition contains YAML errors. Use the  Code Editor to fix the errors and then try again.

To select an item to edit:

• Select an item in the Navigation panel on the left. If the Navigation panel is hidden, click in the sidebar to show it.

— or —

• Click the   arrow in the operation preview or model preview.

  

As you make changes, the API documentation preview is automatically updated to reflect the changes. The editor autosaves drafts every 2 minutes, and you can also save your progress manually at any time. Modified and unsaved items are indicated by a dot ( • ) in the Navigation panel.

To undo any unsaved changes in the editor, use the Revert to Last Saved command.

Click Info in the Navigation panel to edit the API info section, including:

• General info: the API title, description, and terms of service URL

  Note:

  The Version field is read-only. To change the API version, use the Add New Version command in the version list. See Versioning for details.

• Contact info: the contact name, email, and URL

• License info: the license name and URL

• The URL and description of external documentation

Click the image to enlarge it.

Use Visual Editor to quickly edit the summary, description, and add tags to existing operations in your API.

Click the image to enlarge it.

Select a model (schema) in the Navigation panel to edit the model description. Model descriptions support rich text formatting.

Tags are used to group operations into categories in API documentation. You can add tags directly to operations without using the Tags editor. However, if you want to add descriptions and documentation links for tags, you must define these tags explicitly in the Tags editor. The Tags editor corresponds to the global tags section in OpenAPI definitions.

Click Tags in the Navigation panel to access the Tags editor.

To create a new tag, click .

To edit tag metadata, hover over a tag and click .

To reorder tags, click and drag the icon. This will change the tag display order in API documentation.

To delete the global tag definition, hover over a tag and click .

You can leave your comments and ask questions in the in-app support chat, or you can send them to:

https://support.smartbear.com/swaggerhub/message/