Add filename in openapi-schema frontmatter docs

api-playground/openapi-setup.mdx

@@ -14,7 +14,7 @@
 
 ### 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.
@@ -45,9 +45,9 @@
 
 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
 
@@ -92,16 +92,16 @@
 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
 
@@ -158,7 +158,7 @@
 
 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`:
 
@@ -185,7 +185,7 @@
 }
 ```
 
 When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page.
 
 ### MCP
 
@@ -261,14 +261,14 @@
 
 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.
 
 <Tip>
   To exclude specific endpoints from your auto-generated API pages, add the
@@ -283,7 +283,7 @@
 
 ### 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}
 "navigation": {
@@ -366,7 +366,7 @@
 
 #### 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}
 {
@@ -391,7 +391,7 @@
 
 #### Individual endpoints
 
 Reference specific endpoints without setting a default OpenAPI specification by including the file path:
 
 ```json {5-6}
 "navigation": {
@@ -463,7 +463,7 @@
 Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.
 
 <Note>
   Your OpenAPI document must be valid or the files will not autogenerate.
 </Note>
 
 The scraper generates:
@@ -508,9 +508,27 @@
 
 </CodeGroup>
 
+If you have schemas with the same name in multiple files, you can also specify the OpenAPI file:
+
+<CodeGroup>
+
+```mdx Example
+---
+openapi-schema: en-schema.json OrderItem
+---
+```
+
+```mdx Format
+---
+openapi-schema: "path-to-schema-file schema-key"
+---
+```
+
+</CodeGroup>
+
 ## 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