Last modified on June 01, 2023
This page of the documentation describes comments in On-Premise installations. For working with others in SaaS, click here.

The AsyncAPI editor does not support comments.

OpenAPI Code Editor supports comments, so you can share your thoughts and discuss ideas with other collaborators. Comments are used as tickets that bring issues and ideas to the attention of collaborators.

Any user with commenting permissions can add, reply to, resolve, and reopen comments.

Comments are linked to a specific version of an API or domain and are not copied between other versions.

Add comments

Collaborators can add comments on any line of the OpenAPI definition, and can also reply to, resolve, and re-open comments.

To add a comment, click the plus sign to the left of the line number in the editor. This opens the comment panel where you can type your comment.

Adding a comment

Click the image to enlarge it.

Comments support the Markdown syntax for text formatting:

Using Markdown in comments

Click the image to enlarge it.

All the comments appear to the right of the editor, sorted by the line number. To show or hide the comments, click Comments on the editor toolbar. Comments are real-time, so other collaborators who have the API page open will see the comments immediately without refreshing the page.

Using comments

Click the image to enlarge it.

Open and resolved comments

All the comments are grouped into two categories: Open Comments and Resolved Comments. Open comments are unresolved questions and things on the backlog.

Once an issue has been taken care of, you can mark the comment as resolved. This moves the comment to the Resolved Comments section at the bottom.

Resolving a comment

Resolved comments may be deleted or kept for historical purposes. Resolved comments can also be re-opened, if needed.


The following users have commenting permissions:

  • API owner (in case of personal APIs).

  • Organization owners (in case of organization-owned APIs).

  • Collaborators with at least Comment permissions. This includes Designers who created the APIs in question or were added as collaborators.

  • All organization members if the Allow Designers and Consumers to Comment option is enabled for the organization. This option is available in SwaggerHub On-Premise 1.24 and later.

See Also

Sharing APIs
Code Editor for OpenAPI

Highlight search results