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:
- version 3
- in YAML format
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
.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
by the page owner #gds-technical-writing
.
This page was set to be reviewed before 6 July 2022
by the page owner #gds-technical-writing.
This might mean the content is out of date.