Skip to content
Closed
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
76 changes: 39 additions & 37 deletions api-playground/openapi-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
icon: "file-json"
---

OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive API documentation and keep it up to date.
OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0\+ documents to generate interactive API documentation and keep it up to date.

## Add an OpenAPI specification file

Expand All @@ -31,7 +31,7 @@

### 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 @@ -55,37 +55,35 @@

<Steps>
<Step title="Define your authentication method.">
Add a `securitySchemes` field to define how users authenticate.
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": {
"type": "http",
"scheme": "bearer"
```json
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
}
}
```

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

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

```
</Step>
</Steps>

Expand All @@ -107,7 +105,7 @@

Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in `MDX` frontmatter except for `openapi`:

```json {7-13}
```json {7,8,9,10,11,12,13}
{
"paths": {
"/users": {
Expand Down Expand Up @@ -136,7 +134,7 @@

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

```json {6-8}
```json {6,7,8}
{
"paths": {
"/users": {
Expand All @@ -162,7 +160,7 @@

Change the URL of the endpoint page in your docs using `x-mint: href`:

```json {6-8, 14-16}
```json {6,7,8,14,15,16}
{
"paths": {
"/legacy-endpoint": {
Expand Down Expand Up @@ -208,7 +206,8 @@
</ResponseField>

<CodeGroup>
```json Selective enablement {6-9} wrap

```json Selective enablement {6,7,8,9} wrap
{
"paths": {
"/users": {
Expand All @@ -233,7 +232,8 @@
}
```

```json Global enablement {3-5, 9-13} wrap

```json Global enablement {3,4,5,9,10,11,12,13} wrap
{
"openapi": "3.1.0",
"x-mcp": {
Expand All @@ -253,6 +253,7 @@
}
}
```

</CodeGroup>

For more information, see [Model Context Protocol](/ai/model-context-protocol).
Expand Down Expand Up @@ -298,7 +299,7 @@

You can use multiple OpenAPI specifications in different navigation sections:

```json {8-11, 15-18}
```json {8,9,10,11,15,16,17,18}
"navigation": {
"tabs": [
{
Expand Down Expand Up @@ -338,7 +339,7 @@

Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the `pages` field:

```json {12, 15-16}
```json {12,15,16}
"navigation": {
"tabs": [
{
Expand Down Expand Up @@ -368,7 +369,7 @@

OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent's OpenAPI specification unless they define their own:

```json {3, 7-8, 11, 13-14}
```json {3,7,8,11,13,14}
{
"group": "API reference",
"openapi": "/path/to/openapi-v1.json",
Expand All @@ -393,7 +394,7 @@

Reference specific endpoints without setting a default OpenAPI specification by including the file path:

```json {5-6}
```json {5,6}
"navigation": {
"pages": [
"introduction",
Expand Down Expand Up @@ -440,6 +441,7 @@
---
```


```mdx Format
---
title: "title of the page"
Expand All @@ -460,10 +462,10 @@

### 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 465 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L465

Did you really mean 'autogenerate'?

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L468

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

The scraper generates:
Expand All @@ -474,17 +476,16 @@

<Steps>
<Step title="Generate `MDX` files.">
```bash
```bash wrap
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L480

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L485

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 @@ -500,6 +501,7 @@
---
```


```mdx Format
---
openapi-schema: "schema-key"
Expand All @@ -510,7 +512,7 @@

## Webhooks

Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.
Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1\+ documents.

### Define webhooks in your OpenAPI specification

Expand All @@ -533,4 +535,4 @@
<Note>
The webhook name must exactly match the key defined in your OpenAPI
specification's `webhooks` field.
</Note>
</Note>
Loading