Add an API reference without buying a platform
The guide gets someone to a successful request. Later, they need to look up a parameter, check a response, or understand an error. That's the API reference's job.
This tutorial adds a generated reference to the Slot site from part two. You'll describe the demo endpoint in OpenAPI and render it with Speccy, an open-source renderer I built for API documentation.
The result remains a static docs site. You don't need a separate reference platform or an API server running beside the docs.
1. Describe the endpoint
Save this as static/openapi.yaml:
openapi: 3.1.1
info:
title: Slot demo API
version: 1.0.0
description: A local fixture for the documentation tutorial. No real bookings are created.
servers:
- url: http://127.0.0.1:4010
description: Run npm run demo-api on your own computer.
security:
- bearerAuth: []
tags:
- name: Bookings
description: Look up a booking.
paths:
/bookings/{bookingId}:
get:
operationId: getBooking
summary: Find a booking
description: Returns the local example booking. Use book_123 with the demo token.
tags: [Bookings]
parameters:
- name: bookingId
in: path
required: true
description: The identifier of the booking to retrieve.
schema:
type: string
example: book_123
responses:
'200':
description: The booking was found.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
example:
id: book_123
status: confirmed
'401':
description: The demo token is missing or incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: unauthorized
message: Use Bearer demo-key.
'404':
description: The demo only contains book_123.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: not_found
message: Booking not found.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Use the public demo token demo-key.
schemas:
Booking:
type: object
required: [id, status]
properties:
id:
type: string
description: The booking identifier.
status:
type: string
description: The booking's state. The local demo always returns confirmed.
enum: [pending, confirmed, canceled]
Error:
type: object
required: [code, message]
properties:
code:
type: string
description: A machine-readable error code.
message:
type: string
description: An explanation of the error.
The document records the path parameter, authentication, success response, and two failures implemented by the demo. The status enumeration describes the example domain; the demo only returns confirmed.
Keeping the source in static makes the original file available at /openapi.yaml as well as to the build. That lets readers download the contract. Use a local file for this tutorial so publishing the docs doesn't depend on fetching a live service.
2. Install the renderer
From the project root, run:
npm install --save-exact docusaurus-plugin-speccy@0.13.1
In docusaurus.config.ts, add this plugins array alongside presets and themes:
plugins: [
[
'docusaurus-plugin-speccy',
{
route: '/api',
spec: './static/openapi.yaml',
renderer: { tryIt: false },
},
],
],
Keep the glossary preset and local search theme from part two. If you already have a plugins array, append the entry to it.
The plugin adds the /api route. tryIt: false disables the interactive request builder for this fixture. A deployed page shouldn't invite someone to call a local teaching server from the browser. They'll use the curl command in the guide instead.
See Speccy's Docusaurus setup for the renderer and MDX embedding options.
3. Join the reference to the guides
Add an API reference item to the existing themeConfig.navbar.items array:
{ to: '/api', label: 'API reference', position: 'left' },
Add this link to docs/intro.md and docs/find-a-booking.md:
See the [API reference](/api) for the endpoint, parameters, and response schema.
The tutorial explains what to do in order. The reference explains the available contract. Keep both: a generated endpoint page doesn't tell someone how to get credentials, which task to start with, or how a response fits their product.
Local search from part two indexes the Markdown docs. Don't assume it also indexes a route generated by another plugin. The visible API reference navigation item and links from the guides give readers a reliable way to reach this reference.
4. Check the contract against the fixture
Start the demo API in a separate terminal:
npm run demo-api
Request the booking:
curl --include \
http://127.0.0.1:4010/bookings/book_123 \
--header 'Authorization: Bearer demo-key'
Check for HTTP 200, a JSON content type, and a body matching the reference example. Run it again without the header and check for 401. Finally, request /bookings/missing with the header and check for 404.
Those checks connect the written contract to the demo's behavior. The renderer being able to display YAML doesn't prove a real service implements it. For your product, run equivalent checks against the supported sandbox and keep the contract with the code that owns it.
5. Check the published shape
Build and serve the site:
npm run build
npm run serve
Open /api/ directly. Expand Find a booking and check that the booking ID, bearer authentication, response examples, and status choices appear. Follow the reference links from the guide, then use the main navigation to return to the guides. Open /openapi.yaml and confirm that it downloads or displays the source.
Repeat at a narrow browser width. Check that the local docs search and glossary still work. Commit the spec, configuration, content, and updated lockfile, then push. Check those routes on the deployed site too.
You can compare the complete result with the downloadable example.
Cost and maintenance
The renderer runs in the same static site as the guides. It adds no required subscription or server to this example. Your build has more work to do, and you now own the accuracy of an API description as well as the prose.
Speccy also includes API linting and change reports. Those belong in the next stage, where a pull request checks the docs before a customer sees them.
You now have the starting site: a working first task, useful lookup pages, search, definitions, and API reference. Add the advanced pieces when your customers or contributors need them.