# More specs, and your own pages

> For the complete documentation index, see [llms.txt](https://preview.writedocs.io/llms.txt).

Several OpenAPI specs in one site, API groups inside tabs, and replacing a generated endpoint page with one you write.

## 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:

```json
{
  "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:

```json
{
  "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:

```mdx title="docs/api/get-pet.mdx"
---
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.**

> The method and path are matched across every spec in the site. If two specs have the same endpoint, name the spec on the page - see below.

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:

```yaml
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.