|
| 1 | +--- |
| 2 | +title: "Support and Troubleshooting" |
| 3 | +icon: "triangle-exclamation" |
| 4 | +description: "How to get in touch with the Mintlify Team and FAQs" |
| 5 | +--- |
| 6 | + |
| 7 | +The Mintlify team is crafting beautiful docs in San Francisco 🌁 and is most active from 9-5 Pacific Time (UTC -7). |
| 8 | + |
| 9 | +<CardGroup cols="2"> |
| 10 | + <Card title="Dashboard widget" icon="message" iconType="regular" href="https://dashboard.mintlify.com/"> |
| 11 | + You can reach out via the dashboard |
| 12 | + </Card> |
| 13 | + < Card title="Email [email protected]" icon="mailbox-flag-up" iconType="regular" href="mailto:[email protected]"> |
| 14 | + If you can't access the dashboard, email us! |
| 15 | + </Card> |
| 16 | +</CardGroup> |
| 17 | + |
| 18 | +**Frequently Asked Questions:** |
| 19 | + |
| 20 | +<Accordion title="API Page Issues" icon="code-simple"> |
| 21 | + API pages are complicated. As a result, there are a lot of things that can go wrong. Here's a list of common issues we've seen customers run into: |
| 22 | + |
| 23 | + <AccordionGroup> |
| 24 | + <Accordion title="All of my OpenAPI pages are completely blank"> |
| 25 | + In this scenario, it's likely that either Mintlify cannot find your OpenAPI document, |
| 26 | + or your OpenAPI document is invalid. |
| 27 | + |
| 28 | + Running `mintlify dev` locally should reveal some of these issues. |
| 29 | + |
| 30 | + To verify your OpenAPI document will pass validation: |
| 31 | + |
| 32 | + 1. Visit [this validator](https://editor.swagger.io/) |
| 33 | + 2. Switch to the "Validate text" tab |
| 34 | + 3. Paste in your OpenAPI document |
| 35 | + 4. Click "Validate it\!" |
| 36 | + |
| 37 | + If the text box that appears below has a green border, your document has passed validation. |
| 38 | + This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document |
| 39 | + passes validation here, there's a great chance the problem is elsewhere. |
| 40 | + |
| 41 | + Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, |
| 42 | + you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit \> Convert to OpenAPI 3): |
| 43 | + |
| 44 | + <Frame> |
| 45 | +  |
| 46 | + </Frame> |
| 47 | + </Accordion> |
| 48 | + <Accordion title="One of my OpenAPI pages is completely blank"> |
| 49 | + This is usually caused by a misspelled `openapi` field in the page metadata. Make sure |
| 50 | + the HTTP method and path match the HTTP method and path in the OpenAPI document exactly. |
| 51 | + |
| 52 | + Here's an example of how things might go wrong: |
| 53 | + |
| 54 | + ```md get-user.mdx |
| 55 | + --- |
| 56 | + openapi: "GET /users/{id}/" |
| 57 | + --- |
| 58 | + ``` |
| 59 | + |
| 60 | + ```yaml openapi.yaml |
| 61 | + paths: |
| 62 | + "/users/{id}": |
| 63 | + get: ... |
| 64 | + ``` |
| 65 | + Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI |
| 66 | + document does not. |
| 67 | + |
| 68 | + Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document |
| 69 | + in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI |
| 70 | + documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this: |
| 71 | + |
| 72 | + ```md api-reference/v1/users/get-user.mdx |
| 73 | + --- |
| 74 | + openapi: "v1 GET /users/{id}" |
| 75 | + --- |
| 76 | + ``` |
| 77 | + </Accordion> |
| 78 | + <Accordion title="Requests from the API Playground don't work"> |
| 79 | + If you have a custom domain configured, this could be an issue with your reverse proxy. By |
| 80 | + default, requests made via the API Playground start with a `POST` request to the |
| 81 | + `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET` |
| 82 | + requests, then all of these requests will fail. To fix this, configure your reverse proxy to |
| 83 | + allow `POST` requests to the `/api/request` path. |
| 84 | + |
| 85 | + 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 [here](/settings/global#api-configurations). This will |
| 86 | + likely require you to configure CORS on your server, as these requests will now come directly |
| 87 | + from your users' browsers. |
| 88 | + </Accordion> |
| 89 | + </AccordionGroup> |
| 90 | +</Accordion> |
| 91 | + |
| 92 | +<Accordion title="Docs page won't load (error 404)" icon="face-tissue" iconType="regular"> |
| 93 | + Check to see if you have `/api` or `/index` in the URL. These are reserved folders in production environments, which produce a 404 error. |
| 94 | +</Accordion> |
| 95 | + |
| 96 | +<Accordion title="GitHub app issues" icon="code-merge"> |
| 97 | + It is always okay to reset the GitHub app to sort out connection issues. |
| 98 | + |
| 99 | + To do this, you can uninstall the Mintlify app through GitHub: |
| 100 | + |
| 101 | + - go to [installations](https://github.com/settings/installations) -\> click un-install |
| 102 | + - go to [app authorizations](https://github.com/settings/apps/authorizations) -\> click revoke |
| 103 | + |
| 104 | + Then, head to the Mintlify dashboard to reinstall the app (Make sure to install the GitHub app first, then authorize your account): |
| 105 | + |
| 106 | + - [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) |
| 107 | + - [Account settings](https://dashboard.mintlify.com/settings/account) |
| 108 | +</Accordion> |
0 commit comments