Document OpenAPI spec download URLs

api-playground/openapi-setup.mdx

@@ -10,7 +10,7 @@
 
 To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the [OpenAPI specification 3.0 or 3.1](https://swagger.io/specification/).
 
-Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL.
+Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL. Specifications stored in your repository are [served as downloadable files](/create/files) at their path on your docs domain. For example, `https://your-domain/docs/openapi.json`.
 
 Reference any number of OpenAPI specifications in the navigation element of your `docs.json` to create pages for your API endpoints. Each specification file generates its own set of endpoints.
 
@@ -130,7 +130,7 @@
 
 ## Customize your endpoint pages
 
 Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension provides additional control over how your API documentation is generated and displayed.
 
 ### Metadata
 
@@ -208,7 +208,7 @@
 }
 ```
 
 ### Href
 
 Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-mint: href` is present, the generated API page uses the specified URL instead of the default autogenerated URL.
 
@@ -239,11 +239,11 @@
 
 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 appears next to the endpoint title in the side navigation and on the endpoint page.
@@ -259,7 +259,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 are included.
 
 ```json {5}
 "navigation": {
@@ -301,7 +301,7 @@
 ```
 
 <Note>
   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.
 </Note>
 
 ### Selective endpoints
@@ -340,7 +340,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}
 {
@@ -365,7 +365,7 @@
 
 #### Individual endpoints
 
 Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.
 
 ```json {5-6}
 "navigation": {
@@ -417,9 +417,9 @@
 
 </CodeGroup>
 
 The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the file path in your reference. External OpenAPI URLs can be referenced in `docs.json`.
 
 #### Autogenerate endpoint pages
 
 To autogenerate MDX files from your OpenAPI specification, use the Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping).
 
@@ -471,7 +471,7 @@
 
 ## Webhooks
 
 Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.
 
 Add a `webhooks` field to your OpenAPI document alongside the `paths` field.