Comments

Important

The OpenAPI 3.1 specification does not support comments.

OpenAPI Code Editor and AsyncAPI Code Editor support comments, enabling you to share your thoughts and discuss ideas with other users. You can use comments as tickets that bring issues and suggestions to the attention of others. Users with commenting permissions can add, reply to, resolve, and reopen comments.

The system links comments to a specific version of an API or domain and does not copy them between versions.

Comments support the Markdown syntax for text formatting.

Add comments

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

All comments appear to the right of the editor, sorted by line number. To show or hide the comments, click Comments on the editor toolbar.

Create a comment in OpenAPI

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

Comments in OpenAPI are real-time, meaning other users viewing the same API can see comment updates immediately without refreshing the page. However, if the Code Editor has any unsaved changes, you need to submit these changes first before the comments will be available to other users in real time again.

Create a comment in AsyncAPI

To add a new comment, follow the steps below:

Select the fragment of the API you want to comment on. You can add comments to specific strings within a line, whole lines, or multiple lines at once.
Right-click the fragment and select Add Comment. This allows you to save your comment as a draft.
Select Save to Hub in the editor toolbar to make your comment updates visible to other users.

Each commented fragment is highlighted and underscored in the editor.

Comments and resolved comments

The system groups all comments into two categories: Comments and Resolved Comments. Comments are unresolved questions and backlog items.

After you address an issue, mark the comment as resolved. This moves the comment to the Resolved Comments section at the bottom. Note: In AsyncAPI, always select Save to Hub to submit the comment updates.

Resolved comments may be deleted or kept for historical purposes. They can also be reopened if needed.

Who can comment?

The following users have commenting permissions:

Organization owners and designers.
Consumers, if the Allow Consumers to Comment on all the APIs and Domains they can access option is enabled for the organization.