> ## Documentation Index > Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # OpenAPI setup > Reference OpenAPI endpoints in your docs pages 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 To document your endpoints with OpenAPI, you need a valid OpenAPI document in either JSON or YAML format that follows the [OpenAPI specification 3.0+](https://swagger.io/specification/). You can create API pages from a single or multiple OpenAPI documents. ### Describing your API We recommend the following resources to learn about and construct your OpenAPI documents. * [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax. * [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification. * [Swagger Editor](https://editor.swagger.io/) to edit, validate, and debug your OpenAPI document. * [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint openapi-check `. 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. ### 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. ```json theme={null} { "servers": [ { "url": "https://api.example.com/v1" } ] } ``` In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}` or simply `/`. The base URL defines where these paths should be appended. For more information on how to configure the `servers` field, see [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) in the OpenAPI documentation. The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown will allow users to toggle between servers. If you do not specify a server, the API playground will use simple mode since it cannot send requests without a base URL. If your API has endpoints that exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation. ### Specifying authentication To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI document. The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. Add a `securitySchemes` field to define how users authenticate. This example shows a configuration for bearer authentication. ```json theme={null} { "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } } ``` Add a `security` field to require authentication. ```json theme={null} { "security": [ { "bearerAuth": [] } ] } ``` Common authentication types include: * [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): For header, query, or cookie-based keys. * [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): For JWT or OAuth tokens. * [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): For username and password. 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. For more information on defining and applying authentication, see [Authentication](https://swagger.io/docs/specification/authentication/) in the OpenAPI documentation. ## `x-mint` extension The `x-mint` extension is a custom OpenAPI extension that provides additional control over how your API documentation is generated and displayed. ### Metadata 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} theme={null} { "paths": { "/users": { "get": { "summary": "Get users", "description": "Retrieve a list of users", "x-mint": { "metadata": { "title": "List all users", "description": "Fetch paginated user data with filtering options", "og:title": "Display a list of users" } }, "parameters": [ { // Parameter configuration } ] } } } } ``` ### Content Add content before the auto-generated API documentation using `x-mint: content`: ```json {6-8} theme={null} { "paths": { "/users": { "post": { "summary": "Create user", "x-mint": { "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\nUser emails must be unique across the system." }, "parameters": [ { // Parameter configuration } ] } } } } ``` The `content` extension supports all Mintlify MDX components and formatting. ### Href Change the URL of the endpoint page in your docs using `x-mint: href`: ```json {6-8, 14-16} theme={null} { "paths": { "/legacy-endpoint": { "get": { "summary": "Legacy endpoint", "x-mint": { "href": "/deprecated-endpoints/legacy-endpoint" } } }, "/documented-elsewhere": { "post": { "summary": "Special endpoint", "x-mint": { "href": "/guides/special-endpoint-guide" } } } } } ``` When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page. ### MCP Selectively expose endpoints as Model Context Protocol (MCP) tools by using `x-mint: mcp`. Only enable endpoints that are safe for public access through AI tools. The MCP configuration for the endpoint. Whether to expose the endpoint as an MCP tool. Takes precedence over the file-level configuration. The name of the MCP tool. The description of the MCP tool. ```json Selective enablement {6-9} wrap theme={null} { "paths": { "/users": { "post": { "summary": "Create user", "x-mint": { "mcp": { "enabled": true }, // ... } } }, "/users": { "delete": { "summary": "Delete user (admin only)", // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool // ... } } } } ``` ```json Global enablement {3-5, 9-13} wrap theme={null} { "openapi": "3.1.0", "x-mcp": { "enabled": true // All endpoints are exposed as MCP tools by default }, "paths": { "/api/admin/delete": { "delete": { "x-mint": { "mcp": { "enabled": false // Disable MCP for this endpoint } }, "summary": "Delete resources" } } } } ``` For more information, see [Model Context Protocol](/ai/model-context-protocol). ## Auto-populate API pages Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages. The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document. Generated endpoint pages have these default metadata values: * `title`: The operation's `summary` field, if present. If there is no `summary`, the title is generated from the HTTP method and endpoint. * `description`: The operation's `description` field, if present. * `version`: The `version` value from the parent anchor or tab, if present. * `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. 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. There are two approaches for adding endpoint pages into your documentation: 1. **Dedicated API sections**: Reference OpenAPI specs in navigation elements for dedicated API sections. 2. **Selective endpoints**: Reference specific endpoints in your navigation alongside other pages. ### Dedicated API sections Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification will be included: ```json {5} theme={null} "navigation": { "tabs": [ { "tab": "API Reference", "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" } ] } ``` You can use multiple OpenAPI specifications in different navigation sections: ```json {8-11, 15-18} theme={null} "navigation": { "tabs": [ { "tab": "API Reference", "groups": [ { "group": "Users", "openapi": { "source": "/path/to/openapi-1.json", "directory": "api-reference" } }, { "group": "Admin", "openapi": { "source": "/path/to/openapi-2.json", "directory": "api-reference" } } ] } ] } ``` 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. ### Selective endpoints When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach allows you to generate pages for API endpoints alongside other content. #### Set a default OpenAPI spec Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the `pages` field: ```json {12, 15-16} theme={null} "navigation": { "tabs": [ { "tab": "Getting started", "pages": [ "quickstart", "installation" ] }, { "tab": "API reference", "openapi": "/path/to/openapi.json", "pages": [ "api-overview", "GET /users", "POST /users", "guides/authentication" ] } ] } ``` Any page entry matching the format `METHOD /path` will generate an API page for that endpoint using the default OpenAPI spec. #### OpenAPI spec inheritance 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} theme={null} { "group": "API reference", "openapi": "/path/to/openapi-v1.json", "pages": [ "overview", "authentication", "GET /users", "POST /users", { "group": "Orders", "openapi": "/path/to/openapi-v2.json", "pages": [ "GET /orders", "POST /orders" ] } ] } ``` #### Individual endpoints Reference specific endpoints without setting a default OpenAPI specification by including the file path: ```json {5-6} theme={null} "navigation": { "pages": [ "introduction", "user-guides", "/path/to/openapi-v1.json POST /users", "/path/to/openapi-v2.json GET /orders" ] } ``` This approach is useful when you need individual endpoints from different specs or only want to include select endpoints. ## Create `MDX` files for API pages For control over individual endpoint pages, create `MDX` pages for each operation. This lets you customize page metadata, add content, omit certain operations, or reorder pages in your navigation at the page level. See an [example MDX OpenAPI page from MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) and how it appears in their [live documentation](https://docs.mindsdb.com/rest/databases/create-databases). ### Manually specify files Create an `MDX` page for each endpoint and specify which OpenAPI operation to display using the `openapi` field in the frontmatter. When you reference an OpenAPI operation this way, the name, description, parameters, responses, and API playground are automatically generated from your OpenAPI document. 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. 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. If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`. ```mdx Example theme={null} --- title: "Get users" description: "Returns all plants from the system that the user has access to" openapi: "/path/to/openapi-1.json GET /users" deprecated: true version: "1.0" --- ``` ```mdx Format theme={null} --- title: "title of the page" description: "description of the page" openapi: openapi-file-path method path deprecated: boolean (not required) version: "version-string" (not required) --- ``` 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. ### Autogenerate `MDX` files Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents. Your OpenAPI document must be valid or the files will not autogenerate. The scraper generates: * An `MDX` page for each operation in the `paths` field of your OpenAPI document. * If your OpenAPI document is version 3.1+, an `MDX` page for each operation in the `webhooks` field of your OpenAPI document. * An array of navigation entries that you can add to your `docs.json`. ```bash theme={null} npx @mintlify/scraping@latest openapi-file ``` ```bash theme={null} 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. ### Create `MDX` files for OpenAPI schemas You can create individual pages for any OpenAPI schema defined in an OpenAPI document's `components.schema` field: ```mdx Example theme={null} --- openapi-schema: OrderItem --- ``` ```mdx Format theme={null} --- openapi-schema: "schema-key" --- ``` If you have schemas with the same name in multiple files, you can also specify the OpenAPI file: ```mdx Example theme={null} --- openapi-schema: en-schema.json OrderItem --- ``` ```mdx Format theme={null} --- openapi-schema: "path-to-schema-file 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. ### Define webhooks in your OpenAPI specification Add a `webhooks` field to your OpenAPI document alongside the `paths` field. For more information on defining webhooks, see [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) in the OpenAPI documentation. ### Reference webhooks in MDX files When creating MDX pages for webhooks, use `webhook` instead of HTTP methods like `GET` or `POST`: ```mdx theme={null} --- title: "Example webhook" description: "Triggered when an event occurs" 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.