Troubleshooting

All of my OpenAPI pages are completely blank

One of my OpenAPI pages is completely blank

This is usually caused by a misspelled openapi field in the page metadata. Make sure the HTTP method and path match the HTTP method and path in the OpenAPI document exactly.Here’s an example of how things might go wrong:

get-user.mdx

---
openapi: "GET /users/{id}/"
---

openapi.yaml

paths:
  "/users/{id}":
    get: ...

Notice that the path in the openapi field has a trailing slash, whereas the path in the OpenAPI document does not.Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document in the openapi field, ensure the filename is correct. For example, if you have two OpenAPI documents openapi/v1.json and openapi/v2.json, your metadata might look like this:

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

Requests from the API Playground don't work

OpenAPI navigation entries are not generating pages

If you are using an OpenAPI navigation configuration, but the pages aren’t generating, check these common issues:

Missing default OpenAPI spec: Ensure you have an openapi field set for the navigation element:

"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "GET /users",
        "POST /users"
      ]
    }
  ]
}

OpenAPI spec inheritance: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
Validation issues: Use mint openapi-check <path-to-openapi-file> to verify your OpenAPI document is valid.

Some OpenAPI operations appear in navigation but others don't

Mixed navigation (OpenAPI and MDX pages) not working correctly

Getting started

Core configuration

AI optimization

Components

API pages

Authentication and personalization

Guides

Integrations

Version control and CI/CD