Documentation

Everything you need to publish API documentation with API Docket.

Install

A Confluence administrator installs API Docket from the Atlassian Marketplace: open Settings → Apps → Explore apps, search for “API Docket”, and select Try it free. Once installed, admins find API Docket's settings under Settings → Apps → API Docket.

Add documentation to a page

  1. Edit a Confluence page and type /openapi (or /swagger, or /apidocket).
  2. Choose OpenAPI / Swagger (API Docket). The settings dialog opens.
  3. Pick a source, fill in its details and select Test connection.
  4. Adjust the display options if you like, then Save and publish the page.

To change the source later, select the macro in the editor and choose the pencil icon.

Sources

Paste

Paste a YAML or JSON document straight into the macro. Each time you save a changed version, it is added to the changelog. Good for drafts and small APIs.

Attachment

Attach a .yaml, .yml or .json file to the page and choose it in the macro. Upload a new version of the attachment to update the documentation. Attachments are read with the permissions of the person viewing the page.

URL

Any HTTP or HTTPS address that returns an OpenAPI or Swagger document, for example https://petstore3.swagger.io/api/v3/openapi.json. If the URL needs an API key, an admin can add a URL connection.

GitHub, GitLab and Bitbucket

Enter the repository (owner/repo, group/project or workspace/repo), the file path and optionally a branch, tag or commit. Leave the branch empty to use the default branch. GitLab also works with self-managed instances: enter your GitLab host name.

Private files: connections

Public files work without any setup. For private repositories or protected URLs, a Confluence administrator creates a connection in Settings → Apps → API Docket:

  1. Select Add connection and choose the type.
  2. Give it a name page editors will recognise, such as “Acme GitHub”.
  3. List the allowed locations, one per line, for example github.com/acme/ or github.com/acme/payments-api/docs/. The connection can only read files whose location starts with one of these prefixes. Use * to allow everything the token can read.
  4. Paste an access token and save.

Page editors then pick the connection in the macro's settings. They never see the token.

Which token to use

  • GitHub: a fine-grained personal access token (or a GitHub App token) with read-only access to Contents on the repositories you need.
  • GitLab: a project or group access token with the read_repository scope.
  • Bitbucket Cloud: a repository or workspace access token with Repositories: Read. Alternatively, use an Atlassian API token and enter your Atlassian email as the username.
  • URL: any token. By default it is sent as Authorization: Bearer <token>. Set a header name (such as X-API-Key) to send it in a different header, or a username to use Basic authentication.
Tokens are stored with Forge's encrypted secret storage, inside Atlassian's cloud. They are never returned to the browser, and deleting a connection deletes its token.

Try it out

Readers can send real requests from the documentation with Swagger UI's Try it out button. Each macro has three modes:

  • Send via API Docket (default). The request is relayed by API Docket's Forge backend, which avoids the CORS errors browsers raise for requests made from inside Confluence. Requests can only go to the servers listed in the specification's servers (or host) field. Cookies are never forwarded, request bodies are limited to 1 MB and responses to 2 MB.
  • Directly from the browser. The reader's browser sends the request. Use this for APIs only reachable from your internal network (VPN), and make sure the API allows cross-origin requests.
  • Disabled. The documentation is read-only.

Administrators can turn the relay off for the whole site in API Docket's settings. Macros set to Send via API Docket then fall back to sending requests from the browser.

Changelog

Whenever API Docket sees a new version of a specification, it compares it with the previous one and records the differences on the Changelog tab. Each change is labelled:

  • Breaking: existing clients may fail. Removed endpoints, removed response fields, new required parameters or request fields, type changes, removed security schemes.
  • Check: probably fine, but worth reviewing. Deprecations, changed security requirements, removed optional parameters, new enum values in responses.
  • Change: additive or informational. New endpoints, new optional fields, version number changes.

When the latest update contains breaking changes, a red badge appears next to the API title. API Docket keeps the last 50 versions for each source.

How updates work

Linked sources (URL, GitHub, GitLab, Bitbucket, attachments) are cached. When someone views the page and the cached copy is older than the refresh interval, API Docket fetches the file again. The default interval is 15 minutes; admins can change the site default and editors can set it per macro. Readers can select Refresh to fetch the latest version immediately.

If a source becomes unreachable, API Docket keeps showing the last good copy with a warning, so a temporary outage never blanks out your documentation.

Limits

  • Specifications up to 20 MB.
  • OpenAPI 3.0 and 3.1, and Swagger 2.0. AsyncAPI is not supported yet.
  • References to other files ($ref: './schemas/pet.yaml') are not resolved. Bundle multi-file specifications into one file first, for example with npx @redocly/cli bundle.
  • Try it out via API Docket doesn't support multipart file uploads; use the direct mode for those operations.

Troubleshooting

“returned not found (HTTP 404)”

Check the repository, path and branch. GitHub and GitLab also answer 404 for private files when no valid token is used. Ask an admin to add a connection.

“The connection … is not allowed to read …”

The file is outside the connection's allowed locations. An admin can add the location in API Docket's settings.

“Requests can only be sent to the servers declared in this specification”

Try it out via API Docket only contacts servers listed in the document. Add the server to the specification's servers list, or switch the macro to direct mode.

Still stuck?

Email support@apidocket.com with the page link and the error message.