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 3 October 2019. It needs to be reviewed again on 4 October 2019 by the page owner #docs-repos .
This page was set to be reviewed before 4 October 2019 by the page owner #docs-repos. This might mean the content is out of date.