Visual Editor for OpenAPI Definitions

Last modified on September 27, 2023

Available in SwaggerHub SaaS, SwaggerHub On-Premise 1.20.0 and later.

SwaggerHub provides Visual Editor for OpenAPI 2.0 and OpenAPI 3.0 definitions so that you can update your API information without having to understand the YAML syntax. Visual Editor is fully synchronized with the Code Editor. The changes you make in Visual Editor are immediately reflected in the YAML code, and vice versa.

SwaggerHub Visual Editor for OpenAPI

Click the image to enlarge it.

Overview

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).

Note: Domain editing and other functionality not listed above is not supported at this time.

Open Visual Editor

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.

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

Usage

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.

The 'Revert to Last Saved' command

Edit API information

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

SwaggerHub Visual Editor: API info section

Click the image to enlarge it.

Edit operation metadata

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

SwaggerHub Visual Editor: Operation metadata

Click the image to enlarge it.

Edit model descriptions

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

Manage tags

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.

SwaggerHub Visual Editor: Tags
Note: OpenAPI lets you define tags directly in operations. These tags appear in API documentation, but do not appear in the Tags editor unless you create them directly.

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 .

Note: Deleting a tag definition does not automatically delete this tag from operations and API documentation.

Got feedback?

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/

See Also

Code Editor for OpenAPI
SwaggerHub UI Overview
Interactive API Documentation
Custom Branding for API Documentation

Highlight search results