Include easy to browse API documentation into your help center.
API documentation will help developers learn about your API’s functionality and help them adopt it for their purposes.
If you include API documentation directly in your Viewport help center along with any other product documentation, it will be more easier to find and go back to when needed.
As reference material, it’s okay if the pages of your API documentation are longer than other types of content. However, browsability is key. Your users will probably want to skim through the pages, so you want to make sure that they can easily get to the piece of information they need.
Anatomy of the Page
How To Construct the Page
Learn how to re-create the page using the Confluence editor.
Note: The easiest way to insert editor elements and macros is by typing
/ followed by the macro name right into the page.
Create one page per operation
On each page, add a heading 1 or 2 (
/heading 2) to start your first section
Describe the operation and purpose of the operation as normal text
Add a code snippet macro (
/Code snippet) to your page
Set the language of your code snippet
Add bullet points, tables (
/table) to organize any other content
Add more headings to your page. All headings will automatically show in Viewport as part of your table of contents.
Alternative method: Open API macro
If adding and organizing your API documentation manually is too time-consuming for your team, you can also think about using the Open API macro to generate a nicely styled output directly from your JSON or YAML definition:
Please note: The downside of this approach is that the content is rendered dynamically in the Viewport site in the Viewport site in thand can’t therefore be indexed and crawled by search engines or the Viewport search.
Install Open API Documentation for Confluence by O'Hara Group from the Atlassian marketplace
Insert the Open API macro on a Confluence page (type
/Open API (Swagger) Documentationonto your page)
Paste your JSON or YAML definition directly into the macro’s editor or add a URL where the definition is located
Click Insert. Please note: Any macro parameters configured through the Open API app will fall back to the default options
Click Publish in Confluence
Click Update site in Viewport
If you’re pulling the data from an external URL, then your API documentation will update automatically in the Viewport site whenever the data changes in the source. This means: You don’t have to click ‘update site’ in Viewport to update the API documentation.