Visual Editor for OpenAPI Definitions Legacy

Available in API Hub for Design SaaS, API Hub for Design On-Premise 1.20.0 and later.

API Hub for Design 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.

Note

For Form Editor, go to Form Editor for OpenAPI Definitions.

SwaggerHub Visual Editor for OpenAPI

Overview

Using Visual Editor, you can:

  • Edit API information: title, description, license, contact information, and 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.png Show Visual Editor in the sidebar of the API Hub for Design 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

Important

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 show-navigation.png in the sidebar to show it.

— or —

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

    jump-to.png

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

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

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 grip.gif 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:

go.gifhttps://support.smartbear.com/swaggerhub/message/

See Also

Publication date: