Document OpenAPI 3.2 support

api-playground/openapi-setup.mdx

@@ -4,11 +4,11 @@
 keywords: ["OpenAPI", "API specification", "Swagger"]
 ---
 
-OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0 and 3.1 documents to generate interactive API documentation and keep it up to date.
+OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0, 3.1, and 3.2 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 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/).
+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, 3.1, or 3.2](https://spec.openapis.org/oas/latest.html).
 
 Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL. Mintlify serves specifications stored in your repository as [downloadable files](/create/files) at their path on your docs domain. For example, `https://your-domain/docs/openapi.json`.
 
@@ -78,7 +78,7 @@
 - [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint validate`.
 
 <Note>
-  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.
+  Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1 and v3.2. For more information on the differences between versions, 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 and [OpenAPI 3.2 features](#openapi-32-features) below.
 </Note>
 
 ### Specify the base URL for your API
@@ -212,15 +212,15 @@
 
 ## Transform your spec with overlays
 
 Use [OpenAPI Overlays](https://spec.openapis.org/overlay/v1.1.0.html) to modify an OpenAPI specification without editing its source file. Overlays are separate JSON or YAML files that describe an ordered list of changes, which is useful when a specification is generated by another tool or maintained by another team. Common uses include renaming paths, replacing server URLs, and removing internal endpoints.
 
 Overlays apply after a specification is parsed and before it is validated, so generated endpoint pages, navigation, `openapi` frontmatter references, and `mint validate` all use the transformed document. Overlay Specification versions 1.0 and 1.1 are supported.
 
 ### Create an overlay document
 
 An overlay document has an `overlay` version, an `info` object with a `title` and `version`, and an `actions` array. Each action selects nodes with a `target` [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression and applies one modifier:
 
 - `update`: Merges a value into each targeted node. Objects merge recursively, arrays append the value, and primitives are replaced.
 - `remove`: Deletes each targeted node when set to `true`.
 - `copy`: Copies the node selected by another JSONPath expression into each targeted node. Requires Overlay 1.1.
 
@@ -264,11 +264,11 @@
 
 ### Auto-discover overlays
 
 Any JSON or YAML file in your repository with a top-level `overlay` key is treated as an overlay document. If its `extends` field resolves to one of your specifications, the overlay applies to that specification automatically. Auto-discovered overlays apply in alphabetical order of their file paths. Overlays without an `extends` field never apply automatically.
 
 An explicit `overlays` list replaces auto-discovery for that specification. Set `"overlays": []` to disable all overlays for a specification, including auto-discovered ones.
 
 Explicit and auto-discovered overlays fail differently. If an explicit overlay fails to load or apply, the specification fails validation and the deployment reports a spec error. If an auto-discovered overlay fails, it is skipped and the specification publishes without it.
 
 ### Rename a path
 
@@ -307,7 +307,7 @@
 When enabled, clicking the option downloads your OpenAPI spec directly. Deployments with multiple specs receive them bundled as `api-specs.zip`. On deployments behind `auth` or `userAuth`, only authenticated readers can download the spec.
 
 <Warning>
   The downloaded OpenAPI spec is unfiltered and does not respect [authentication groups](/deploy/authentication-setup). Any authenticated reader who can open the contextual menu receives the full spec, including endpoints and schemas that would otherwise be hidden from their group. Do not enable `download-spec` on an authenticated site if your OpenAPI spec contains endpoints or fields you consider sensitive.
 </Warning>
 
 ## Customize your endpoint pages
@@ -420,7 +420,7 @@
 
 ### Collapse playground fields
 
 Collapse object-type fields in the API playground by default using `x-mint: playground` with `expand: false` on any operation. Request sections like Authorization, Headers, Query, Path, and Body always stay expanded, and so does the top-level body object. Object fields nested within them start collapsed, so readers expand only the fields they want to interact with. If `expand` is not set, object fields are expanded by default.
 
 ```json {6-10}
 {
@@ -823,3 +823,116 @@
                 "200":
                   description: Callback received
 ```
+
+## OpenAPI 3.2 features
+
+OpenAPI 3.2 documents (`openapi: 3.2.0`) are validated against the official 3.2 schema and support every addition listed here. Documents written for 3.0 or 3.1 keep working unchanged.
+
+### Tag hierarchies
+
+Use the `parent` field on tags to nest generated navigation groups, `summary` for a short display name, and `kind` to mark tags as `nav`, `badge`, or `audience`. Only `nav` tags (the default) create navigation groups.
+
+```yaml
+tags:
+  - name: plants
+    summary: Plants
+  - name: plants.care
+    summary: Care
+    parent: plants
+  - name: beta
+    kind: badge
+```
+
+### QUERY and custom methods
+
+The `query` operation is a fixed Path Item field like `get` or `post`. Other methods go under `additionalOperations`, keyed by their uppercase method name. Both generate endpoint pages, playground requests, and code samples.
+
+```yaml
+paths:
+  /plants:
+    query:
+      summary: Search plants
+    additionalOperations:
+      PURGE:
+        summary: Purge the plant cache
+```
+
+Reference these operations in MDX frontmatter with the same method name you used in the specification. Fixed methods are case-insensitive, while custom methods are uppercase:
+
+```mdx
+---
+openapi: "openapi.yaml PURGE /plants"
+---
+```
+
+`WEBHOOK` cannot be used as a custom method because it identifies [webhook pages](#webhooks).
+
+### Whole query string parameters
+
+Describe the entire query string with a single `in: querystring` parameter whose `content` gives the media type. The playground renders it as its own **Query string** input and serializes `application/x-www-form-urlencoded`, `application/json`, and `text/*` content exactly once. An operation can have at most one `querystring` parameter and cannot combine it with `in: query` parameters.
+
+```yaml
+parameters:
+  - name: filter
+    in: querystring
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            color:
+              type: string
+```
+
+### Streaming responses
+
+Use `itemSchema` instead of `schema` on a sequential media type such as `text/event-stream`, `application/jsonl`, `application/x-ndjson`, `application/json-seq`, or `multipart/mixed` to describe each item in the stream. Endpoint pages show the item fields under **Each item in the stream**, and the playground displays the response incrementally as it arrives with a **Stop** control. Streams larger than 10 MB are truncated in the viewer, and streams sent through the Mintlify proxy end after 5 minutes.
+
+```yaml
+responses:
+  "200":
+    description: Plant events
+    content:
+      text/event-stream:
+        itemSchema:
+          type: object
+          properties:
+            event:
+              type: string
+```
+
+### Data and serialized example values
+
+Example Objects can carry `dataValue` for the logical value and `serializedValue` for the exact wire representation. Endpoint pages render `serializedValue` verbatim with syntax highlighting based on the media type, and the playground uses `dataValue` to prefill inputs. `externalValue` points to a hosted serialized document.
+
+### Security schemes
+
+- **Device authorization flow**: OAuth 2.0 schemes can declare `flows.deviceAuthorization` with a `deviceAuthorizationUrl` and `tokenUrl`. The playground shows a **Connect** panel that requests a device code, displays the user code and verification URL, polls the token endpoint, and applies the access token to the request. Public clients (`client_id` only) are supported.
+- **Metadata URL**: `oauth2MetadataUrl` is listed with the flow details on the endpoint page.
+- **Deprecated schemes**: Schemes marked `deprecated: true` show a deprecated pill and label in the authorization selector.
+- **URI references**: Security requirement keys can reference a scheme by URI fragment, such as `#/components/securitySchemes/oauth`, in addition to the component name. References to other documents are not supported.
+
+### Discriminator default mapping
+
+Set `discriminator.defaultMapping` to the schema used when the discriminating property is absent or unmapped. That variant is listed first in the docs, selected by default in the playground, and used for generated examples. The value must be a `mapping` value, a `components.schemas` name, or a same-document reference.
+
+### Parameter serialization
+
+- `style: cookie` on `in: cookie` parameters follows RFC 6265 and applies no percent-encoding.
+- `allowReserved: true` on query and path parameters keeps reserved characters unencoded in generated requests and code samples. Query delimiters (`&`, `=`, `#`) and `/` in path segments are still encoded.
+- `prefixEncoding` and `itemEncoding` on multipart Media Type Objects and Encoding Objects set per-part content types in code samples. They require `itemSchema` or an array `schema`.
+
+### Document-level fields
+
+- `$self` is preserved as the document's base URI.
+- `servers[].name` labels each entry in the base URL selector.
+- Responses can use `summary` alone or with `description`; the heading shows `description` when present, otherwise `summary`. Every server variable can appear at most once in a server URL.
+- Reusable Media Type Objects in `components.mediaTypes` can be referenced from any `content` map with `$ref`.
+
+### Limitations
+
+- Operations that live only under `components.pathItems` do not generate pages. Reference them from `paths` instead.
+- Browsers do not let the playground set a `Cookie` header, so `in: cookie` parameters appear in code samples but are not sent by live requests.
+- Positional multipart encodings set content types in code samples that write the multipart body themselves. Live browser requests and the Node `fetch` sample use `FormData`, which cannot set a content type on a non-file field, so those parts are sent as plain fields.
+- XML Object fields (`nodeType` and IRI namespaces) validate but are not rendered; the playground does not generate XML bodies.
+- Webhook pages resolve to the first operation on a webhook Path Item, so declare one operation per webhook.