diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index de396cc57..a556895ed 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -4,7 +4,7 @@ description: "Reference OpenAPI endpoints in your docs pages"
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
@@ -55,37 +55,35 @@ To enable authentication in your API documentation and playground, configure the
- 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"
+ }
+ }
}
}
- }
-}
-```
-
+ ```
- Add a `security` field to require authentication.
+ Add a `security` field to require authentication.
-```json
-{
- "security": [
+ ```json
{
- "bearerAuth": []
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ]
}
- ]
-}
-```
-
+ ```
@@ -107,7 +105,7 @@ The `x-mint` extension is a custom OpenAPI extension that provides additional co
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": {
@@ -136,7 +134,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
Add content before the auto-generated API documentation using `x-mint: content`:
-```json {6-8}
+```json {6,7,8}
{
"paths": {
"/users": {
@@ -162,7 +160,7 @@ The `content` extension supports all Mintlify MDX components and formatting.
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": {
@@ -208,7 +206,8 @@ Selectively expose endpoints as Model Context Protocol (MCP) tools by using `x-m
-```json Selective enablement {6-9} wrap
+
+```json Selective enablement {6,7,8,9} wrap
{
"paths": {
"/users": {
@@ -233,7 +232,8 @@ Selectively expose endpoints as Model Context Protocol (MCP) tools by using `x-m
}
```
-```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": {
@@ -253,6 +253,7 @@ Selectively expose endpoints as Model Context Protocol (MCP) tools by using `x-m
}
}
```
+
For more information, see [Model Context Protocol](/ai/model-context-protocol).
@@ -298,7 +299,7 @@ Generate dedicated API sections by adding an `openapi` field to a navigation ele
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": [
{
@@ -338,7 +339,7 @@ When you want more control over where endpoints appear in your documentation, yo
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": [
{
@@ -368,7 +369,7 @@ Any page entry matching the format `METHOD /path` will generate an API page for
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",
@@ -393,7 +394,7 @@ OpenAPI specifications are inherited down the navigation hierarchy. Child naviga
Reference specific endpoints without setting a default OpenAPI specification by including the file path:
-```json {5-6}
+```json {5,6}
"navigation": {
"pages": [
"introduction",
@@ -440,6 +441,7 @@ version: "1.0"
---
```
+
```mdx Format
---
title: "title of the page"
@@ -474,17 +476,16 @@ The scraper generates:
- ```bash
+ ```bash wrap
npx @mintlify/scraping@latest openapi-file
```
- ```bash
+ ```bash wrap
npx @mintlify/scraping@latest openapi-file -o api-reference
```
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.
-
@@ -500,6 +501,7 @@ openapi-schema: OrderItem
---
```
+
```mdx Format
---
openapi-schema: "schema-key"
@@ -510,7 +512,7 @@ openapi-schema: "schema-key"
## 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
@@ -533,4 +535,4 @@ openapi: "path/to/openapi-file webhook example-webhook-name"
The webhook name must exactly match the key defined in your OpenAPI
specification's `webhooks` field.
-
+
\ No newline at end of file