More specs, and your own pages

Several specs

Any number of groups can use openapi, each with its own spec - a public API and an admin API in the same site, say:

{
  "navigation": [
    "index",
    {
      "group": "REST API",
      "openapi": { "src": "rest-api.yaml", "path": "/api/rest" }
    },
    {
      "group": "Admin API",
      "openapi": { "src": "admin-api.yaml", "path": "/api/admin" }
    }
  ]
}

Each group needs its own path. Two groups with the same one are an error in writedocs validate, naming both.

An openapi group goes anywhere a group can - inside another group, a tab, a version - at any depth. An API reference tab with two specs:

{
  "navigation": {
    "tabs": [
      { "tab": "Guides", "pages": ["index"] },
      {
        "tab": "API Reference",
        "pages": [
          { "group": "REST", "openapi": { "src": "rest-api.yaml", "path": "/api/rest" } },
          { "group": "GraphQL", "openapi": { "src": "graphql-api.yaml", "path": "/api/graphql" } }
        ]
      }
    ]
  }
}

Your own page for an endpoint

Some endpoints need more than the spec says - a longer explanation, more examples, a warning. Write a page for the endpoint, and set its openapi frontmatter to the endpoint’s method and path, exactly as in the spec:

---
title: Get a pet by ID
description: Retrieve a single pet's details, with troubleshooting notes for the common 404 case.
openapi: "GET /pets/{petId}"
---

This endpoint 404s if the pet was soft-deleted rather than removed outright — check the
`X-Deleted-At` response header before assuming the ID is simply wrong.

When the endpoint is in a spec:

• Your page replaces the generated one for that endpoint: your text, then the same parameters, responses and Try it playground.
• Every other endpoint keeps its generated page.

List the page in the navigation like any other page. An openapi value that matches no endpoint is a warning in writedocs validate, and the page shows a notice where the endpoint would be.

Naming the spec on the page

A page can name its spec, before the method:

openapi: "/openapi.yaml GET /pets/{petId}"

The spec’s path is from the project folder. A spec named this way doesn’t need an openapi group: write a page for each endpoint you want, and list them in the navigation like any pages - useful for a small API, or to choose which endpoints to show. If the spec also has an openapi group, the page replaces that endpoint’s generated page, as above.