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