diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx index 3bcc30a7e..f0a247a50 100644 --- a/api-playground/openapi/writing-openapi.mdx +++ b/api-playground/openapi/writing-openapi.mdx @@ -12,21 +12,26 @@ There are many great tools online for learning about and constructing OpenAPI do - [Swagger's Editor](https://editor.swagger.io/) for seeing examples in action - Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). + Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information about the differences between v3.0 and v3.1, check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). ## Specifying the URL for your API -In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}`, or maybe simply `/`. To specify the base URL to which these paths should be appended, OpenAPI provides the `servers` field. This field is necessary to use some Mintlify features like the API Playground. Read how to configure the `servers` field in the [Swagger documentation](https://swagger.io/docs/specification/api-host-and-base-path/). +In an OpenAPI document, different API endpoints are specified by their paths, such as `/users/{id}` or simply `/`. To specify the base URL to which these paths should be appended, OpenAPI provides the `servers` field. This field is necessary to use some Mintlify features like the API Playground. Learn how to configure the `servers` field in the [Swagger documentation](https://swagger.io/docs/specification/api-host-and-base-path/). The API Playground will use these server URLs to determine where to send requests. If multiple servers are specified, a dropdown will appear to allow toggling between servers. If no server is supplied, the API Playground will use simple mode, as there is no way to send a request. If different endpoints within your API exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) for a given path or operation. -## Specifying authentication +## Specifying Authentication -Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/), [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/), and [API Keys](https://swagger.io/docs/specification/authentication/api-keys/). To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out [Swagger's documentation and examples](https://swagger.io/docs/specification/authentication/) on the topic. +Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the authentication methods used throughout your API. It includes simple configuration for the most common authentication types: +- [Basic Authentication](https://swagger.io/docs/specification/authentication/basic-authentication/) +- [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) +- [API Keys](https://swagger.io/docs/specification/authentication/api-keys/) + +To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. Since the syntax for defining and applying authentication can be unintuitive, we recommend reviewing [Swagger's documentation and examples](https://swagger.io/docs/specification/authentication/) on the topic. The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. -If different endpoints within your API require different methods of authentication, you can [override the security field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation. +If different endpoints within your API require different methods of authentication, you can [override the security field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation. \ No newline at end of file diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index 4b411e6a1..41320cf6c 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -4,17 +4,16 @@ 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: +API pages can be complex, and there are several common issues you might encounter. Here's a list of problems our customers frequently experience and their solutions: - In this scenario, it's likely that either Mintlify cannot find your OpenAPI document, + If you're experiencing this issue, 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. + Running `mintlify dev` locally should help identify these issues. - To verify your OpenAPI document will pass validation: + To verify that your OpenAPI document will pass validation: 1. Visit [this validator](https://apitools.dev/swagger-parser/online/) 2. Switch to the "Validate text" tab @@ -22,11 +21,13 @@ Here's a list of common issues we've seen customers run into: 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. + This is the exact validation package that Mintlify uses to validate OpenAPI documents. If your document + passes validation here, the problem likely lies 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): + Note: Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, + you may encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) by following these steps: + 1. Go to Edit + 2. Select "Convert to OpenAPI 3" @@ -35,10 +36,10 @@ Here's a list of common issues we've seen customers run into: - 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. + This issue typically occurs when the `openapi` field in the page metadata is misspelled. Ensure + that the HTTP method and path match exactly with those in the OpenAPI document. - Here's an example of how things might go wrong: + Here's an example of a common mismatch: ```md get-user.mdx --- @@ -52,12 +53,12 @@ paths: get: ... ``` - Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI + Notice that the path in the `openapi` field has a trailing slash, while 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: + Another common issue is a misspelled filename. When specifying a particular OpenAPI document + in the `openapi` field, verify that the filename is correct. For example, if you have two OpenAPI + documents `openapi/v1.json` and `openapi/v2.json`, your metadata should look like this: ```md api-reference/v1/users/get-user.mdx --- @@ -68,17 +69,17 @@ 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 + If you have a custom domain configured, this might be an issue with your reverse proxy. By + default, requests made via the API Playground begin 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 + requests, all of these requests will fail. To resolve 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.disableProxy` - 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. + If your reverse proxy prevents you from accepting `POST` requests, you have an alternative solution. + You can configure Mintlify to send requests directly to your backend using the `api.playground.disableProxy` + setting in the `docs.json`, as described in our [configuration documentation](/settings/global#api-configurations). + Please note that this approach 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/content/components/accordion-groups.mdx b/content/components/accordion-groups.mdx index 29f90169c..1f2fded10 100644 --- a/content/components/accordion-groups.mdx +++ b/content/components/accordion-groups.mdx @@ -1,13 +1,13 @@ --- title: "Accordion Groups" -description: "Group multiple accordions into a single display." +description: "Group multiple Accordions into a single display." icon: "table-rows" --- -Simply add `` around your existing `` components. +Simply add an `` component around your existing `` components. - + You can put other components inside Accordions. ```java HelloWorld.java @@ -20,20 +20,20 @@ Simply add `` around your existing `` components. - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + Check out the [Accordion](/content/components/accordions) documentation for all supported props. - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + Check out the [Accordion](/content/components/accordions) documentation for all supported props. -````jsx Accordion Group Example +```jsx Accordion Group Example - + You can put other components inside Accordions. ```java HelloWorld.java @@ -46,16 +46,16 @@ Simply add `` around your existing `` components. - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + Check out the [Accordion](/content/components/accordions) documentation for all supported props. - - Check out the [Accordion](/content/components/accordions) docs for all the supported props. + + Check out the [Accordion](/content/components/accordions) documentation for all supported props. -```` +``` -`AccordionGroup` does not have any props. +The `AccordionGroup` component does not accept any props. \ No newline at end of file diff --git a/docs.json b/docs.json index 381cdcce0..78d813cc6 100644 --- a/docs.json +++ b/docs.json @@ -22,7 +22,10 @@ { "group": "Editing", "icon": "pen-paintbrush", - "pages": ["development", "web-editor"] + "pages": [ + "development", + "web-editor" + ] }, "settings/global", { @@ -61,7 +64,8 @@ "pages": [ "api-playground/openapi/setup", "api-playground/openapi/writing-openapi", - "api-playground/openapi/advanced-features" + "api-playground/openapi/advanced-features", + "api-playground/openapi/writing-openapi" ] }, { @@ -72,6 +76,7 @@ "api-playground/mdx/authentication" ] }, + "api-playground/troubleshooting", "api-playground/troubleshooting" ] }, @@ -115,7 +120,8 @@ "settings/authentication-personalization/authentication-setup/password", "settings/authentication-personalization/authentication-setup/jwt", "settings/authentication-personalization/authentication-setup/oauth", - "settings/authentication-personalization/authentication-setup/mintlify" + "settings/authentication-personalization/authentication-setup/mintlify", + "settings/authentication-personalization/authentication-setup/jwt" ] }, { @@ -124,6 +130,7 @@ "settings/authentication-personalization/personalization-setup/choosing-a-handshake", "settings/authentication-personalization/personalization-setup/shared-session", "settings/authentication-personalization/personalization-setup/jwt", + "settings/authentication-personalization/personalization-setup/oauth", "settings/authentication-personalization/personalization-setup/oauth" ] }, @@ -133,7 +140,10 @@ { "group": "Dashboard Access", "icon": "house-lock", - "pages": ["advanced/dashboard/sso", "advanced/dashboard/permissions"] + "pages": [ + "advanced/dashboard/sso", + "advanced/dashboard/permissions" + ] }, { "group": "REST API", @@ -181,7 +191,8 @@ "content/components/steps", "content/components/tabs", "content/components/tooltips", - "content/components/update" + "content/components/update", + "content/components/accordion-groups" ] }, { @@ -205,7 +216,7 @@ "pages": [ "integrations/analytics/overview", "integrations/analytics/amplitude", - "integrations/analytics/clearbit", + "integrations/analytics/clearbit", "integrations/analytics/fathom", "integrations/analytics/google-analytics", "integrations/analytics/google-tag-manager", @@ -251,7 +262,9 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog/overview"] + "pages": [ + "changelog/overview" + ] } ] } @@ -363,4 +376,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx index 985ab2a91..28bd8aefc 100644 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -7,20 +7,20 @@ description: 'Use a customized login flow to authenticate users' This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different. -If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL. +If you don't have a dashboard or want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL. ## Implementation - Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend. + Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where your backend can access it. - Create a login flow that does the following: - - Authenticate the user - - Create a JWT containing the authenticated user's info in the [User](../sending-data) format - - Sign the JWT with the secret key, using the EdDSA algorithm - - Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash + Create a login flow that performs the following steps: + - Authenticates the user + - Creates a JWT containing the authenticated user's info in the [User](../sending-data) format + - Signs the JWT with the secret key using the EdDSA algorithm + - Creates a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash Return to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings. @@ -29,20 +29,21 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs ## Example -I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs -to be completely separate from my dashboard (or I don’t have a dashboard at all). +Let's say you want to set up authentication for your docs hosted at `docs.foo.com`. You want your docs to be completely separate from your dashboard (or you don't have a dashboard at all). -To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a -JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow -for my users. At the end of this login flow, once I have verified the identity of the user, -I create a JWT containing the user’s custom data according to Mintlify’s specification. -I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the -form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user. +To set up authentication with Mintlify: -I then go to the dashboard settings and enter `https://foo.com/docs-login` for the -Login URL field. +1. Go to your Mintlify dashboard and generate a JWT secret +2. Create a web URL `https://foo.com/docs-login` that initiates a login flow for your users +3. After verifying the user's identity at the end of the login flow: + - Create a JWT containing the user's custom data according to Mintlify's specification + - Use a JWT library to sign this JWT with your Mintlify secret + - Create a redirect URL in the format: `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}` + - Redirect the user to this URL -Here's what the code might look like: +Finally, go to the dashboard settings and enter `https://foo.com/docs-login` in the Login URL field. + +Here's what the implementation code might look like: ```ts TypeScript @@ -86,7 +87,7 @@ async def return_mintlify_auth_status(current_user): jwt_token = jwt.encode( payload={ 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration - 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration + 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 2 week session expiration 'groups': ['admin'] if current_user.is_admin else [], 'content': { 'firstName': current_user.first_name, @@ -106,14 +107,12 @@ async def return_mintlify_auth_status(current_user): When an unauthenticated user tries to access a specific page, Mintlify preserves their intended destination through a redirect flow: 1. The user attempts to visit a certain page (e.g., `/quickstart`) - 2. Mintlify redirects them to your login URL and adds the (relative) original destination as a `redirect` query parameter Example: * Original request: [`https://docs.foo.com/quickstart`](https://docs.foo.com/quickstart) - * Redirect to login: [`https://foo.com/docs-login?redirect=%2Fquickstart`](https://foo.com/docs-login?redirect=%2Fquickstart) After successful authentication, you can include this same `redirect` parameter in your JWT callback URL to send users to their intended destination: -`https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}` +`https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}` \ No newline at end of file diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx index d72f1be27..0cc61596c 100644 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -7,39 +7,43 @@ description: 'Integrate with your OAuth server to enable user login via the PKCE This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different. -If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. +If you have an existing OAuth server that supports the PKCE (Proof Key for Code Exchange) flow, you can integrate it with Mintlify for a seamless login experience. ## Implementation - Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format. Take note of the scope or scopes required to access this endpoint. + Create an API endpoint that can be accessed with an OAuth access token. This endpoint should respond with a JSON payload following the [User](../sending-data) format. Make sure to note the scope or scopes required to access this endpoint. - Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields: + Navigate to your [dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the following required fields: - - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters. - - **Client ID**: An ID for the OAuth 2.0 client to be used. - - **Scopes**: An array of scopes that will be requested. + - **Authorization URL**: The base URL for the authorization request. Mintlify will automatically append the appropriate query parameters. + - **Client ID**: The identifier for the OAuth 2.0 client to be used. + - **Scopes**: An array of scopes that will be requested during authentication. - **Token URL**: The base URL for the token exchange request. - - **Info API URL**: The endpoint that will be hit to retrieve user info. + - **Info API URL**: The endpoint that will be called to retrieve user information. - Copy the Redirect URL listed in the [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server. + Locate the Redirect URL listed in the [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL in your OAuth server configuration. ## Example -I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`. +Let's say you have an existing OAuth server that supports the PKCE flow, and you want to set up authentication for your documentation hosted at `foo.com/docs`. -To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification. +To implement this with Mintlify: -I then go to the dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint: -- **Authorization URL**: `https://auth.foo.com/authorization` -- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` -- **Scopes**: `['docs-user-info']` -- **Token URL**: `https://auth.foo.com/exchange` -- **Info API URL**: `https://api.foo.com/docs/user-info` +1. Create an endpoint at `api.foo.com/docs/user-info` that: + - Requires an OAuth access token with the `docs-user-info` scope + - Responds with the user's custom data according to Mintlify's specification -Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings. +2. In the dashboard settings, navigate to the Personalization settings, select OAuth, and enter the following values: + - **Authorization URL**: `https://auth.foo.com/authorization` + - **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` + - **Scopes**: `['docs-user-info']` + - **Token URL**: `https://auth.foo.com/exchange` + - **Info API URL**: `https://api.foo.com/docs/user-info` + +3. Finally, copy the Redirect URL from the dashboard settings and add it as an authorized redirect URL in your OAuth client configuration settings. \ No newline at end of file