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
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.
uri_prefix parameter tells Doctave the URL namespace your spec should be
accessible in. In this case, the spec will be accessible under
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.
navigation.yaml file, and include the following at the bottom of
- heading: API items: - open_api_spec: openapi.json
Here we tell Doctave to generate the navigation structure
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
its own element, and the operations for that tag are included as children for
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.
Since OpenAPI 3.0 does not include native support for webhooks, you can render
your webhooks via the
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
openapi: '3.0' info: ... tags: [...] x-webhooks: pet-update: post: summary: Triggered on pet update events operationId: update-pet tags: - Pets requestBody: ... responses: ...
There are a few limitations with the current Doctave OpenAPI implementation:
- Only local references are supported with
- Your spec must be included as a single file
- OpenAPI 3.1 and Swagger 2.0 are not supported
Was this page helpful?