Skip to content

Commit 53d6c5b

Browse files
committed
Creating a support page
This is a version 1 Would love to refine and receive feedback and refine
1 parent ffd2d62 commit 53d6c5b

File tree

3 files changed

+109
-78
lines changed

3 files changed

+109
-78
lines changed

api-playground/support.mdx

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
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+
![](/images/convert-oas-3.png)
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>

api-playground/troubleshooting.mdx

Lines changed: 0 additions & 77 deletions
This file was deleted.

docs.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@
8080
"api-playground/mdx/authentication"
8181
]
8282
},
83-
"api-playground/troubleshooting"
83+
"api-playground/support"
8484
]
8585
},
8686
{

0 commit comments

Comments
 (0)