Topics

• Use x-topics
• External references
• Public documentation examples

x-topics is a vendor-specific property that we’ve created to allow you to add extended content to your API documentation. They enable you to add context, additional information, or even tutorial elements to guide your readers in using your API.

Use x-topics #

Example:

x-topics:
  - title: Getting started
    content: Before using the API you need to get an API key by sending us an email.
  - title: Authentication
    content: Send the `X-API-KEY` header with all your requests.
    example: |
      ```
      $ curl \
        -X POST https://api.example.com/endpoint/ \
        -H "X-API-KEY: XXXXXX" \
      ```

External references #

You can write your topics in dedicated Markdown files to keep your OpenAPI definition file clean. To reference a Markdown file, add a $ref link inside the content object of your topic.

x-topics:
  - title: Getting started
    content: 
      $ref: ./getting-started.md
  - title: Authentication
    content:
      $ref: ./authentication.md
    example:
      $ref: ./authentication-example.md

Public documentation examples #

Here are some examples of public documentation made by teams using x-topics:

• Memo Bank API Documentation
• Pexip Engage API Documentation