From 66e8e576c657d18a5eb73f32f4af31f2ecb78164 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 12 Apr 2025 06:12:40 +0000 Subject: [PATCH] Documentation edits made through Mintlify web editor --- api-playground/support.mdx | 110 +++++++++++++++++++++++++++++ api-playground/troubleshooting.mdx | 77 -------------------- docs.json | 2 +- 3 files changed, 111 insertions(+), 78 deletions(-) create mode 100644 api-playground/support.mdx delete mode 100644 api-playground/troubleshooting.mdx diff --git a/api-playground/support.mdx b/api-playground/support.mdx new file mode 100644 index 000000000..ef6e40565 --- /dev/null +++ b/api-playground/support.mdx @@ -0,0 +1,110 @@ +--- +title: "Support and Troubleshooting" +icon: "triangle-exclamation" +description: "How to get in touch with the Mintlify Team and FAQs" +mode: "wide" +--- + +The Mintlify team is crafting beautiful docs in San Francisco 🌁 and is most active from 9-5 Pacific Time (UTC -7). + + + + You can reach out via the dashboard + + + If you can't access the dashboard, email us\! + + + +**Frequently Asked Questions:** + + + 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: + + + + In this scenario, it's likely that either Mintlify cannot find your OpenAPI document, + or your OpenAPI document is invalid. + + Running `mintlify dev` locally should reveal some of these issues. + + To verify your OpenAPI document will pass validation: + + 1. Visit [this validator](https://editor.swagger.io/) + 2. Switch to the "Validate text" tab + 3. Paste in your OpenAPI document + 4. 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](https://editor.swagger.io/) (under Edit \> Convert to OpenAPI 3): + + + ![](/images/convert-oas-3.png) + + + + 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: + + ```md get-user.mdx + --- + openapi: "GET /users/{id}/" + --- + ``` + + ```yaml 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: + + ```md api-reference/v1/users/get-user.mdx + --- + openapi: "v1 GET /users/{id}" + --- + ``` + + + 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 [here](/settings/global#api-configurations). This will + likely require you to configure CORS on your server, as these requests will now come directly + from your users' browsers. + + + + + + Check to see if you have `/api` or `/index` in the URL. These are reserved folders in production environments, which produce a 404 error. + + + + It is always okay to reset the GitHub app to sort out connection issues. + + To do this, you can uninstall the Mintlify app through GitHub: + + - go to [installations](https://github.com/settings/installations) -\> click un-install + - go to [app authorizations](https://github.com/settings/apps/authorizations) -\> click revoke + + Then, head to the Mintlify dashboard to reinstall the app (Make sure to install the GitHub app first, then authorize your account): + + - [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) + - [Account settings](https://dashboard.mintlify.com/settings/account) + \ No newline at end of file diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx deleted file mode 100644 index 4da6667a6..000000000 --- a/api-playground/troubleshooting.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Troubleshooting" -description: "Common issues with API References" -icon: "triangle-exclamation" ---- - -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: - - - - In this scenario, it's likely that either Mintlify cannot find your OpenAPI document, - or your OpenAPI document is invalid. - - Running `mintlify dev` locally should reveal some of these issues. - - To verify your OpenAPI document will pass validation: - - 1. Visit [this validator](https://editor.swagger.io/) - 2. Switch to the "Validate text" tab - 3. Paste in your OpenAPI document - 4. 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](https://editor.swagger.io/) (under Edit \> Convert to OpenAPI 3): - - - ![](/images/convert-oas-3.png) - - - - 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: - - ```md get-user.mdx - --- - openapi: "GET /users/{id}/" - --- - ``` - - ```yaml 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: - - ```md api-reference/v1/users/get-user.mdx - --- - openapi: "v1 GET /users/{id}" - --- - ``` - - - 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 [here](/settings/global#api-configurations). This will - likely require you to configure CORS on your server, as these requests will now come directly - from your users' browsers. - - \ No newline at end of file diff --git a/docs.json b/docs.json index 76faaeb9f..d6af004d9 100644 --- a/docs.json +++ b/docs.json @@ -80,7 +80,7 @@ "api-playground/mdx/authentication" ] }, - "api-playground/troubleshooting" + "api-playground/support" ] }, {