Comments
Swagger Studio Code Editor supports 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 are available for all API protocols in the Code Editor and support Markdown syntax for text formatting.
Add comments
Designers and consumers can add comments to any selected fragment of the OpenAPI or AsyncAPI definition, and can also reply to, resolve, and reopen 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
To add a new comment, follow the steps below:
Select the fragment of the API you want to comment on. You can add a comment to a specific string in a line, a whole line, or multiple lines at once.
Right-click the fragment and select Add Comment.
The Comments panel displays.
Type in your comment and then click Comment to submit.
For non-draft API definitions, the comment is immediately saved and visible to other users.
For draft API definitions, the comment is saved as a draft comment. Other users cannot see it.
(Only when working in draft mode) To make your comment visible to others, submit your API by selecting Save to Hub.
Note
If another user has modified the same API draft before you submit it, the system shows a warning indicating that saving the definition will overwrite their changes.
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.