Skip to content

Fix Grammar and Spelling Across Documentation #535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Fix Grammar and Spelling Across Documentation #535

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions api-playground/openapi/writing-openapi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

<Note>
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).
</Note>

## 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.
51 changes: 26 additions & 25 deletions api-playground/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,30 @@ 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:

<AccordionGroup>
<Accordion title="All of my OpenAPI pages are completely blank">
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
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.
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"

<Frame>
<img src="/images/convert-oas-3.png" />
Expand All @@ -35,10 +36,10 @@ Here's a list of common issues we've seen customers run into:
</Accordion>

<Accordion title="One of my OpenAPI pages is completely blank">
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
---
Expand All @@ -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
---
Expand All @@ -68,17 +69,17 @@ openapi: "v1 GET /users/{id}"
</Accordion>

<Accordion title="Requests from the API Playground don't work">
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.

</Accordion>
</AccordionGroup>
</AccordionGroup>
30 changes: 15 additions & 15 deletions content/components/accordion-groups.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 `<AccordionGroup>` around your existing `<Accordion>` components.
Simply add an `<AccordionGroup>` component around your existing `<Accordion>` components.

<AccordionGroup>
<Accordion title="FAQ without Icon">
<Accordion title="FAQ Without Icon">
You can put other components inside Accordions.

```java HelloWorld.java
Expand All @@ -20,20 +20,20 @@ Simply add `<AccordionGroup>` around your existing `<Accordion>` components.

</Accordion>

<Accordion title="FAQ with Icon" icon="alien-8bit">
Check out the [Accordion](/content/components/accordions) docs for all the supported props.
<Accordion title="FAQ With Icon" icon="alien-8bit">
Check out the [Accordion](/content/components/accordions) documentation for all supported props.
</Accordion>

<Accordion title="FAQ without Icon">
Check out the [Accordion](/content/components/accordions) docs for all the supported props.
<Accordion title="FAQ Without Icon">
Check out the [Accordion](/content/components/accordions) documentation for all supported props.
</Accordion>
</AccordionGroup>

<RequestExample>

````jsx Accordion Group Example
```jsx Accordion Group Example
<AccordionGroup>
<Accordion title="FAQ without Icon">
<Accordion title="FAQ Without Icon">
You can put other components inside Accordions.

```java HelloWorld.java
Expand All @@ -46,16 +46,16 @@ Simply add `<AccordionGroup>` around your existing `<Accordion>` components.

</Accordion>

<Accordion title="FAQ with Icon" icon="alien-8bit">
Check out the [Accordion](/content/components/accordions) docs for all the supported props.
<Accordion title="FAQ With Icon" icon="alien-8bit">
Check out the [Accordion](/content/components/accordions) documentation for all supported props.
</Accordion>

<Accordion title="FAQ without Icon">
Check out the [Accordion](/content/components/accordions) docs for all the supported props.
<Accordion title="FAQ Without Icon">
Check out the [Accordion](/content/components/accordions) documentation for all supported props.
</Accordion>
</AccordionGroup>
````
```

</RequestExample>

`AccordionGroup` does not have any props.
The `AccordionGroup` component does not accept any props.
29 changes: 21 additions & 8 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,10 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
"pages": [
"development",
"web-editor"
]
},
"settings/global",
{
Expand Down Expand Up @@ -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"
]
},
{
Expand All @@ -72,6 +76,7 @@
"api-playground/mdx/authentication"
]
},
"api-playground/troubleshooting",
"api-playground/troubleshooting"
]
},
Expand Down Expand Up @@ -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"
]
},
{
Expand All @@ -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"
]
},
Expand All @@ -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",
Expand Down Expand Up @@ -181,7 +191,8 @@
"content/components/steps",
"content/components/tabs",
"content/components/tooltips",
"content/components/update"
"content/components/update",
"content/components/accordion-groups"
]
},
{
Expand All @@ -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",
Expand Down Expand Up @@ -251,7 +262,9 @@
"groups": [
{
"group": "Changelog",
"pages": ["changelog/overview"]
"pages": [
"changelog/overview"
]
}
]
}
Expand Down Expand Up @@ -363,4 +376,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
}
}
Loading
Loading