Skip to content
Merged
Changes from all commits
Commits
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
65 changes: 39 additions & 26 deletions api-playground/openapi-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,16 @@
- [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint openapi-check <openapiFilenameOrUrl>`.

<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, see [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) in the OpenAPI blog.
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, see [Migrating from OpenAPI 3.0 to
3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)
in the OpenAPI blog.
</Note>

### Specifying the URL for your API

To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API's base URL.

Check warning on line 34 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L34

Did you really mean 'API's'?

```json
{
Expand All @@ -53,34 +57,34 @@
<Step title="Define your authentication method.">
Add a `securitySchemes` field to define how users authenticate.

This example shows a configuration for bearer authentication.
This example shows a configuration for bearer authentication.

```json
{
"components": {
"securitySchemes": {
"bearerAuth": {
```json
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
}
```

</Step>
<Step title="Apply authentication to your endpoints.">
Add a `security` field to require authentication.

```json
{
"security": [
{
"bearerAuth": []
}
]
}
```
```json
{
"security": [
{
"bearerAuth": []
}
]
}
```

</Step>
</Steps>
Expand Down Expand Up @@ -114,7 +118,7 @@
"metadata": {
"title": "List all users",
"description": "Fetch paginated user data with filtering options",
"og:title": "Display a list of users",
"og:title": "Display a list of users"
}
},
"parameters": [
Expand All @@ -132,7 +136,7 @@

Add content before the auto-generated API documentation using `x-mint: content`:

```json {6-13}
```json {6-8}
{
"paths": {
"/users": {
Expand Down Expand Up @@ -223,7 +227,9 @@
- `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label will appear next to the endpoint title in the side navigation and on the endpoint page.

<Tip>
To exclude specific endpoints from your auto-generated API pages, add the [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) property to the operation in your OpenAPI spec.
To exclude specific endpoints from your auto-generated API pages, add the
[x-hidden](/api-playground/customization/managing-page-visibility#x-hidden)
property to the operation in your OpenAPI spec.
</Tip>

There are two approaches for adding endpoint pages into your documentation:
Expand Down Expand Up @@ -275,7 +281,9 @@
```

<Note>
The `directory` field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the `api-reference` directory of your repo.
The `directory` field is optional and specifies where generated API pages are
stored in your docs repo. If not specified, defaults to the `api-reference`
directory of your repo.
</Note>

### Selective endpoints
Expand Down Expand Up @@ -369,7 +377,9 @@
If you have multiple OpenAPI files, include the file path in your reference to ensure Mintlify finds the correct OpenAPI document. If you have only one OpenAPI file, Mintlify will detect it automatically.

<Note>
This approach works regardless of whether you have set a default OpenAPI spec in your navigation. You can reference any endpoint from any OpenAPI spec by including the file path in the frontmatter.
This approach works regardless of whether you have set a default OpenAPI spec
in your navigation. You can reference any endpoint from any OpenAPI spec by
including the file path in the frontmatter.
</Note>

If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`.
Expand Down Expand Up @@ -399,15 +409,17 @@
</CodeGroup>

<Note>
The method and path must exactly match the definition in your OpenAPI specification. If the endpoint doesn't exist in the OpenAPI file, the page will be empty.
The method and path must exactly match the definition in your OpenAPI
specification. If the endpoint doesn't exist in the OpenAPI file, the page
will be empty.
</Note>

### Autogenerate `MDX` files

Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.

Check warning on line 419 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L419

Did you really mean 'autogenerate'?

<Note>
Your OpenAPI document must be valid or the files will not autogenerate.

Check warning on line 422 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L422

Did you really mean 'autogenerate'?
</Note>

The scraper generates:
Expand All @@ -419,15 +431,16 @@
<Steps>
<Step title="Generate `MDX` files.">
```bash
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>

Check warning on line 434 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L434

Did you really mean 'npx'?
```
</Step>
<Step title="Specify an output folder.">
```bash
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference

Check warning on line 439 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L439

Did you really mean 'npx'?
```

Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.

</Step>
</Steps>

Expand All @@ -443,7 +456,6 @@
---
```


```mdx Format
---
openapi-schema: "schema-key"
Expand Down Expand Up @@ -475,5 +487,6 @@
```

<Note>
The webhook name must exactly match the key defined in your OpenAPI specification's `webhooks` field.
The webhook name must exactly match the key defined in your OpenAPI
specification's `webhooks` field.
</Note>