OpenAPI Reference Documentation

Doctave can generate API reference documentation from your OpenAPI 3.0 specifications. 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 OpenAPI spec

First, place your OpenAPI 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 doesn't 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 doesn't 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:
	...

x-doctave-tags

You can use the x-doctave-tags to place an API operation under another tag in docs only. It functions exactly as tags.

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

In the above example, the described POST endpoint would result in being placed under the "Animals" tag.

Code Samples

You can include custom code samples that show how to invoke your operation.

Code samples are added at the operation level, under the x-doctave and code-samples fields:

openapi: '3.0'
info: # ...
tags: [...]
paths:
  /example:
    get:
      # (other fields omitted)
      x-doctave:
        code-samples:
          - language: rust
            code: |
              let client = Client::new(project_id);
              let session = client.collaboration_session().create().await?;

          - language: javascript
            code: |
              // JavaScript code example
          - language: python
            code: |
              # Python code example
          - language: ruby
            code: |
              # Ruby code example
          - language: go
            code: |
              // Go code example

These will get rendered on the right side of the operation with the appropriate syntax highlighting applied for the language:

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 aren't supported