API References

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.

Live Demo

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.

1. Create one page per operation

2. On each page, add a heading 1 or 2 (/heading 2) to start your first section

3. Describe the operation and purpose of the operation as normal text

4. Add a code snippet macro (/code snippet) to your page

5. Set the language of your code snippet

6. Add bullet points, tables (/table) to organize any other content

7. 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.

1. Install Open API Documentation for Confluence by O'Hara Group from the Atlassian marketplace

2. Insert the Open API macro on a Confluence page (type /Open API (Swagger) Documentation onto your page)

3. Paste your JSON or YAML definition directly into the macro’s editor or add a URL where the definition is located

4. Click Insert. Please note: Any macro parameters configured through the Open API app will fall back to the default options

5. Click Publish in Confluence

6. 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.