Set Up an API Reference

Add an OpenAPI spec to your Mordoc project and see generated API pages in minutes.

1 MIN READ

This page takes you from an OpenAPI file to a running API reference.

You need an existing Mordoc project. If you do not have one, start with Create a Project.

Step 1: Add the spec

Copy your OpenAPI file into the api/specs/ folder. Create the folders if they do not exist.

Text

api/specs/rings.yaml

Not sure the spec is ready? See Prepare Your Spec.

Create config/api.yaml and give the spec an id and its file name:

Yaml

- id: rings
  spec: rings.yaml

The id names the API in folders and URLs. Use letters, digits, hyphens, and underscores only. See API Registry for every option.

Add the operations to your sidebar with operation: and the spec's operationId:

Yaml

- label: Rings API
  expanded: true
  children:
    - operation: forgeRing
    - operation: getRing

See Link Operations in Navigation for groups, labels, and guide pages.

Bash

npm run dev

Open the site and click one of the new sidebar links.

Each operation gets a page at /api/<id>/<operation-slug>. The slug is the operationId in kebab-case:

`operationId`	Page URL
`forgeRing`	`/api/rings/forge-ring`
`getRing`	`/api/rings/get-ring`

You can change the /api/<id> part with routePrefix. See API Registry.

See it live

The Retrieve a ring page was generated from a spec with no extra work.

Add one entry per spec. Each spec gets its own id, its own URL prefix, and its own enrichment folder:

Yaml

- id: fellowship
  spec: fellowship.yaml
- id: rings
  spec: rings.yaml