Breadcrumbs

API References (Help Center)

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 Scroll site 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

📺

API Resources: Accounts

Anatomy of the Page

Child pages

Having a page for each operation, for example will make it easier for users to overview the available content right away.

Table of Contents

Allow your users to jump to the relevant sections.

Code Snippet

Insert code into a code container with numbered lines, syntax highlighting and a 'copy code' option.

Showing an example page with API references


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 your help center 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 Scroll site and can’t therefore be indexed and crawled by search engines or the site’s 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. Publish the changes in Scroll Sites.

If you’re pulling the data from an external URL, then your API documentation will update automatically in the Scroll site whenever the data changes in the source.