OpenAPI Specs

Doctave supports including OpenAPI 3.0 specifications in your documentation. They will be rendered alongside the rest of your Markdown content under the same domain.

Lets walk through how to include an OpenAPI spec file in your project.

Including your spec

First, place your spec file (YAML or JSON) in your project directory (the directory with your doctave.yaml file).

Next, update your doctave.yaml and reference the spec file:

title: My docs
...
open_api:
  - spec_file: openapi.json
    uri_prefix: /api

You can include multiple OpenAPI specification files in a single project.

The uri_prefix parameter tells Doctave the URL namespace your spec should be accessible in. In this case, the spec will be accessible under /api.

Updating your navigation

Including the spec alone in the project does not yet make it visible. You need to update your navigation structure to reference the new OpenAPI pages.

Luckily, Doctave provides a convenience method for this, which will generate the navigation structure from the spec itself. You specify where in the navigation structure to place the links, and Doctave will do the rest.

Open your navigation.yaml file, and include the following at the bottom of the file:

- heading: API
  items:
  - open_api_spec: openapi.json

Here we tell Doctave to generate the navigation structure from the openapi.json file and include it under the API section. You can also choose to place the open_api_spec section under a different parent.

After you save the file, the navigation should update. Every OpenAPI tag gets its own element, and the operations for that tag are included as children for that element.

Page structure

Doctave generates a separate page for each of your OpenAPI tags. These pages will include every operation or the tag, in the order in which they appear in the OpenAPI spec file.

Supported extensions

x-webhooks

Since OpenAPI 3.0 does not include native support for webhooks, you can render your webhooks via the x-webhooks extension.

You can place your webhook definitions, which will follow the same schema as regular OpenAPI operations, under the x-webhooks tag at the top level of your schema.

openapi: '3.0'
info: ...
tags: [...]
x-webhooks:
  pet-update:
    post:
      summary: Triggered on pet update events
      operationId: update-pet
      tags:
        - Pets
      requestBody:
        ...
      responses:
	... 

Limitations

There are a few limitations with the current Doctave OpenAPI implementation:

• Only local references are supported with $ref properties.
• Your spec must be included as a single file
• OpenAPI 3.1 and Swagger 2.0 are not supported