OpenAPI setup

Use OpenAPI when you want Docsalot to render endpoint pages from a spec instead of maintaining every operation by hand.

​

1. Add your spec file

Keep the spec inside the docs repo so preview and production use the same source of truth.

docsalot-docs/
  layout.json
  openapi/
    docsalot-cli-v1.json

JSON and YAML both work as long as the document validates as OpenAPI 3.x.

​

2. Register shared API defaults

Add your API defaults in layout.json. If you keep multiple specs, you can register them here too.

{
  "api": {
    "openapi": "openapi/docsalot-cli-v1.json",
    "baseUrl": "https://docsalot.dev/api/cli/v1",
    "auth": {
      "method": "bearer"
    }
  }
}

​

3. Create endpoint pages

The smallest setup is one MDX file per operation with openapi: frontmatter.

---
title: "Get current user"
openapi: "GET /auth/user"
description: "Return the current user associated with the bearer token."
---

The HTTP method and path need to match the operation in the spec.

​

4. Generate sections from navigation

When you want a full reference section, attach an OpenAPI source to a navigation group and optionally list only the operations you want exposed.

{
  "group": "API Reference",
  "openapi": "openapi/docsalot-cli-v1.json",
  "pages": [
    "GET /auth/user",
    "GET /documentations",
    "POST /documentations"
  ]
}

This keeps the navigation curated while still letting the rendered pages come from the spec.

​

5. Keep a downloadable source

If readers need to import your contract into Postman, Insomnia, or a code generator, publish a direct spec download page such as OpenAPI Spec.

​

Good defaults

• Keep your spec under a dedicated openapi/ folder.
• Use OpenAPI-backed pages for stable endpoints and manual pages only where you need custom storytelling.
• Validate the spec before previewing so broken operations do not render as blank pages.

If you need a lighter-weight page for a single endpoint, continue to Create manual API pages.