Troubleshooting
Common issues with API References
If your API pages aren’t displaying correctly, check these common configuration issues:
All of my OpenAPI pages are completely blank
All of my OpenAPI pages are completely blank
In this scenario, it’s likely that either Mintlify cannot find your OpenAPI document, or your OpenAPI document is invalid.
Running mint dev
locally should reveal some of these issues.
To verify your OpenAPI document will pass validation:
- Visit this validator
- Switch to the “Validate text” tab
- Paste in your OpenAPI document
- Click “Validate it!”
If the text box that appears below has a green border, your document has passed validation. This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document passes validation here, there’s a great chance the problem is elsewhere.
Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, you could encounter this issue. You can convert your document at editor.swagger.io (under Edit > Convert to OpenAPI 3):
One of my OpenAPI pages is 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:
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:
Requests from the API Playground don't work
Requests from the API Playground don't work
If you have a custom domain configured, this could be an issue with your reverse proxy. By
default, requests made via the API Playground start with a POST
request to the
/api/request
path on the docs site. If your reverse proxy is configured to only allow GET
requests, then all of these requests will fail. To fix this, configure your reverse proxy to
allow POST
requests to the /api/request
path.
Alternatively, if your reverse proxy prevents you from accepting POST
requests, you can configure Mintlify to send requests directly to your backend with the api.playground.proxy
setting in the docs.json
, as described in the settings documentation. When using this configuration, you will need to configure CORS on your server since requests will come directly from users’ browsers rather than through your proxy.