API reference

Point Axerity at an OpenAPI 3 spec and it generates the whole reference for you: a page per operation with parameters, request and response bodies, examples, auth, and a page per schema. The pages use the same API components you would write by hand, so they match the rest of your docs.

Point at a spec

Add an openapi field to axerity.json. The simplest form is a path or URL:

{	"openapi": "./openapi.json"}

The spec can be a local file or a URL, in JSON or YAML:

{	"openapi": "https://api.example.com/openapi.yaml"}

Pages are written into your content tree the next time you run axerity dev or axerity build, and they regenerate when a local spec changes.

Choose where it lands

Use the object form to set the output folder and the section title:

{	"openapi": {		"spec": "./openapi.json",		"output": "api-reference",		"title": "API Reference"	}}

With output: "api-reference", an operation tagged Pet lands at /api-reference/pet/<operationId> and each schema at /api-reference/schemas/<name>.

Group several specs

Pass an array to generate more than one reference, each into its own folder:

{	"openapi": [		{ "spec": "./checkout.json", "output": "checkout-api", "title": "Checkout" },		{ "spec": "./storefront.json", "output": "storefront-api", "title": "Storefront" }	]}

Show it as a navbar tab

The generated pages are ordinary docs, so you surface them like any other area: add a dropdown that points at the output folder. Clicking the tab swaps the sidebar to the API reference.

{	"dropdowns": [		{			"label": "API Reference",			"icon": "code",			"href": "/api-reference/pet/getpetbyid",			"match": "/api-reference"		}	]}

Set href to any page inside the folder (a good landing operation), and match to the folder so the tab highlights while the reader is anywhere in the reference.