Documenting your APIs with the Atlassian REST API Browser
The Atlassian REST API Browser (RAB) is a tool for discovering REST and other types of remote APIs exposed by Atlassian applications. The RAB displays the APIs exposed by the application as well as by any plugins installed in the application.
This page tells you how to use RAB to document any REST resources that you have added to an Atlassian application. (For more about how client developers would use the RAB, see Using the REST API Browser.)
Adding a REST resource that will appear in RAB
If you add a REST API to a plugin using the SDK and install the plugin to the Atlassian application, the RAB automatically displays its REST API. You only need to add the API descriptions that you want to appear in the RAB.
To add those descriptions, use Javadoc annotations described in the Oracle guide to writing Javadoc comments: How to Write Doc Comments for the Javadoc Tool. RAB will display the inline documentation inside the browser.
- There are some additional Javadoc tags that you can use to provide REST-specific documentation.
- You can also include a custom
application-doc.xmlfile in your
src/main/resources/folder that can provide any custom static documentation in the WADL file.
- Mark your APIs with one of these annotations:
@ExperimentalApi. Any resource without one of these two annotations will be treated as private. These annotations are defined in the
atlassian-annotationlibrary, which your Atlassian application should already be using. Other developers who have your plugin installed will consider public APIs safe to use in their own code, whereas experimental APIs will be considered subject to change.
The RAB source code is available on Bitbucket.