Skip to content

Latest commit

 

History

History
93 lines (59 loc) · 3.42 KB

openapi-extensions.md

File metadata and controls

93 lines (59 loc) · 3.42 KB

OpenAPI extensions

These are the extensions which we support and our own brand new ones!

Existing extensions

These are the existing extensions we support:

x-logo

This extension adds a logo to the documentation. It is inspired by the x-logo extensions described by Redocly and by APIs.guru, but our version adds the path field.

x-logo is the Logo object, described below.

x-logo is a property of the Info object.

Logo Object

Fixed Fields

Either url or path MUST be provided. Giving both means undefined behaviour.

Field Name Type Description
url string REQUIRED if path is not present. URL of the logo. SHOULD be loadable by a web browser. SHOULD be an absolute URL so the API definition is usable from any location.
path string REQUIRED if url is not present. Path to the logo file, relative to the OpenAPI file.
backgroundColor string Background colour for the logo. CSS color (#RRGGBB).
altText string Text to use for alt tag on the logo. Defaults to 'logo' if not given.

x-pages

This extension allows arbitrary markdown pages with extra documentation.

x-pages is an array of Page or Separator Objects, described below.

x-pages can be a property of:

Page Object

Fixed Fields

Field Name Type Description
name string REQUIRED. The name of this page.
slug string Used as the page id / anchor. This must be unique across the entire file. If not given, it is auto-generated in a way that ensures it is unique.
tags [string] A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
content string Markdown, the page's content.

Separator Object

Notes a break between pages. This may be shown as, for example, a <hr> separator in a navigation bar, or in any other way. Multiple separators in a row should be collapsed into just one. Separators at the beginning or end of an array (not between two Page objects) should be ignored.

Fixed Fields

Field Name Type Description
separator boolean REQUIRED. True. Says that this is a separator.

x-pages examples

A simple list of extra pages:

x-pages:
  - name: Authentication
    slut: auth
    tags:
      - api-basics
    content: |
      The API endpoints use OAuth. Here's how:
      ...

  - name: Weights and Volumes
    tags:
      - api-basics
    content: |
      We use weight and volume to determine the 'size' of your parcel.

      This page describes how to think about weights and volumes.

x-pages todos

  • Add x-pages field inside Path objects.
  • Add pages field inside Page object for more complex layouts.
    • if done, maybe a way to specify which levels should result in page breaks and which should not be page breaks?