Skip to main content

Convert an OpenAPI specification into documentation

OpenAPI is an API description format for REST APIs. The government’s Open Standards Board recommends using OpenAPI.

You can convert an OpenAPI file into an API reference page in your documentation.

Your OpenAPI file must be both:

  1. Add the following to your config/tech-docs.yml file:

    api_path: <OPENAPI_FILE>

    where <OPENAPI_FILE> is your OpenAPI file, for example /openapi/openapi.yaml.

  2. Add the following in your documentation to convert the OpenAPI file into an API reference:

    api>

For api_path you can also use:

  • a relative path, for example ./openapi/openapi.yaml
  • an external file, for example https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml

Convert a specific endpoint

You can convert a specific endpoint using the following in your documentation:

api> <ENDPOINT>

where <ENDPOINT> is your endpoint, for example /pets.

This page was last reviewed on 6 July 2021. It needs to be reviewed again on 6 July 2022 .