diff --git a/support.mdx b/support.mdx index 304b43a60..aff5d9061 100644 --- a/support.mdx +++ b/support.mdx @@ -32,101 +32,102 @@ export function openSearch(e) { ## Frequently Asked Questions - - The GitHub app can be temperamental and resetting the connection is a great way to solve issues. - - - - 1. In GitHub, go to [installations](https://github.com/settings/installations) and select **Configure** next to the Mintlify app. Scroll down and select **Uninstall**. - 2. Go to [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) and select **Revoke** next to the Mintlify app. - - - 1. In your Mintlify dashboard, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and install the GitHub app. - 2. Authorize your account in the [My Profile](https://dashboard.mintlify.com/settings/account) section of your dashboard. - - - - - - 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 `mint dev` locally should reveal some of these issues. - - To verify your OpenAPI document will pass validation: - - 1. Run `mint openapi-check ` in your CLI. - 2. Validate your OpenAPI spec with [Swagger Editor](https://editor.swagger.io/). - - Additionally, Mintlify does not support OpenAPI 2.0. If your document uses OpenAPI 2.0, you may encounter this issue. You can convert your document with [Swagger Editor](https://editor.swagger.io/). - - - !["Convert to OpenAPI 3" menu item highlighted in the Swagger Editor](/images/convert-oas-3.png) - - - - This is usually caused by a misspelled `openapi` field in the page metadata. Make sure that 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`. See the [configurations for the API playground](/settings#param-proxy) for more information. 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` in the URL. This is a reserved folder in production environments, which produces a 404 error. - - - - -We support a specific type of SVG, called JSX, and as such the image will need to be converted. - -1. Use the [SVGR converter](https://react-svgr.com/playground/) to generate JSX compatible SVG code. -2. Copy the code inside the `` tag. - -![Output from the SVGR converter with the code inside and tags highlighted.](/images/svg-jsx.png) - -3. Paste the code into your card. Make sure you only copy and paste the code inside the `` tag. -4. You may need to decrease the height and width to make the image fit. - - + + + The GitHub app can be temperamental and resetting the connection is a great way to solve issues. + + + + 1. In GitHub, go to [installations](https://github.com/settings/installations) and select **Configure** next to the Mintlify app. Scroll down and select **Uninstall**. + 2. Go to [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) and select **Revoke** next to the Mintlify app. + + + 1. In your Mintlify dashboard, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and install the GitHub app. + 2. Authorize your account in the [My Profile](https://dashboard.mintlify.com/settings/account) section of your dashboard. + + + + + + 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 `mint dev` locally should reveal some of these issues. + + To verify your OpenAPI document will pass validation: + + 1. Run `mint openapi-check ` in your CLI. + 2. Validate your OpenAPI spec with [Swagger Editor](https://editor.swagger.io/). + + Additionally, Mintlify does not support OpenAPI 2.0. If your document uses OpenAPI 2.0, you may encounter this issue. You can convert your document with [Swagger Editor](https://editor.swagger.io/). + + + !["Convert to OpenAPI 3" menu item highlighted in the Swagger Editor](/images/convert-oas-3.png) + + + + This is usually caused by a misspelled `openapi` field in the page metadata. Make sure that 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`. See the [configurations for the API playground](/settings#param-proxy) for more information. 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` in the URL. This is a reserved folder in production environments, which produces a 404 error. + + + + + We support a specific type of SVG, called JSX, and as such the image will need to be converted. + + 1. Use the [SVGR converter](https://react-svgr.com/playground/) to generate JSX compatible SVG code. + 2. Copy the code inside the `` tag. + + ![Output from the SVGR converter with the code inside and tags highlighted.](/images/svg-jsx.png) + + 3. Paste the code into your card. Make sure you only copy and paste the code inside the `` tag. + 4. You may need to decrease the height and width to make the image fit. + + We do our best to respond to all requests within 24 hours but delays may occur during busy times.