Updated openapi-schema documentation for filepath parameter

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:
@@ -500,17 +500,47 @@
 ---
 ```
 
+```mdx With specific file
+---
+openapi-schema: path/to/openapi.json OrderItem
+---
+```
+
 ```mdx Format
 ---
 openapi-schema: "schema-key"
+# or
+openapi-schema: "filepath schema-key"
 ---
 ```
 
 </CodeGroup>
 
+When you have multiple OpenAPI files with schemas that have the same name, you can specify which file to use by including the filepath before the schema name. This is useful for multi-language documentation where you have translated versions of the same schema in different OpenAPI files.
+
+#### Example use case
+
+If you have multiple OpenAPI specifications with the same schema name but different content (such as translated descriptions), you can specify which file to use:
+
+```mdx English schema page
+---
+title: "Plant schema"
+openapi-schema: specs/en/openapi.json Plant
+---
+```
+
+```mdx German schema page  
+---
+title: "Plant schema (German)"
+openapi-schema: specs/de/openapi.json Plant
+---
+```
+
+Both pages reference a schema named `Plant`, but the English page will show the schema from `specs/en/openapi.json` while the German page will show the schema from `specs/de/openapi.json`, allowing you to display localized schema descriptions and field names.
+
 ## 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