Skip to main content
Table of contents

Add an OpenAPI specification to your documentation

OpenAPI is an API description format for RESTful APIs. The GDS Open Standards board recommends that government organisations use OpenAPI version 3 to describe RESTful APIs.

The template can extract endpoint information from an Open API v3 specification in a YAML file.

Amend the tech-docs.yml file

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

api_path: path/to/file.yaml

This can be a relative path to a file in your tech docs repo folder, for example:

api_path: ./source/pets.yaml

This can also be a URL to a file hosted elsewhere, for example:

api_path: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

Amend the content file

Add the following line to the content file that you want to output the API information to:

api>

You can specify individual endpoints to be outputted rather than all API information, for example::

api> /pets
This page was last reviewed on 1 July 2020. It needs to be reviewed again on 1 July 2021 by the page owner #tech-writers .
This page was set to be reviewed before 1 July 2021 by the page owner #tech-writers. This might mean the content is out of date.