OpenAPI 3.2 is nearly here. As of August 2025, over 94% of the 151 issues listed in its official milestone have been resolved. A release is expected soon, and for API producers and documentation tools alike, it introduces capabilities that enable more structured, flexible, and real-world documentation.

At Zylo-docs—our platform that turns OpenAPI specs into rich, interactive documentation—we’ve been closely tracking the 3.2 changes. Several updates stand out, but three in particular have direct implications for how teams can organize, extend, and simulate APIs more effectively.

The first is the introduction of structured tags. Previously limited to simple arrays, tags in 3.2 can now be defined as objects, complete with metadata like summary, description, and most notably, a parent field that enables nested tag hierarchies:

tags:
partner:
name: partner
summary: Partner APIs
description: Operations for partners
parent: external
kind: audience

This allows documentation tools to group and organize APIs more meaningfully—by feature, role, or audience—with less custom logic and more semantic clarity.

Another long-awaited improvement is support for extended HTTP methods, particularly QUERY. While QUERY is a valid HTTP method according to the protocol, OpenAPI has historically limited its method support to those commonly associated with RESTful architectures—such as GET, POST, PUT, and DELETE. This was a deliberate design choice to encourage RESTful design, but it left developers using non-standard methods without a way to fully document their APIs.

In version 3.2, OpenAPI introduces a new field, additionalOperations, that allows these additional methods to be defined safely and cleanly:

paths:
/search:
get:
summary: Basic search
additionalOperations:
query:
summary: Find pets by ID
description: Returns pets based on ID
operationId: queryPetsById
responses:
'200':
description: pet response
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/Pet'

With this addition, tools can maintain compatibility while supporting real-world implementations. Frameworks like FastAPI are expected to adopt this quickly, and at Zylo-docs, we’re already preparing to support rendering and testing for extended methods like QUERY just as seamlessly as standard ones.

Finally, OpenAPI 3.2 introduces robust support for multipart media types beyond the familiar multipart/form-data. Developers can now document complex combinations like multipart/mixed, multipart/related, and multipart/byteranges. These are useful for describing partial content responses, multi-part HTML payloads, or mixed-format streams. For instance:

multipart/mixed:
schema:
type: array
prefixItems:
- type: object
- {}
prefixEncoding:
- {}
- contentType: image/*

This change gives developers precise tools to describe advanced response formats that were previously hard to represent. Zylo-docs is actively implementing support to let users define, preview, and test multipart responses with confidence.

As the OpenAPI specification evolves to better reflect the complexity and flexibility of modern APIs, we’re committed to evolving alongside it. If you’re curious how Zylo-docs brings OpenAPI 3.2 to life—or just want to chat about documentation, dev tools, or standards—feel free to connect with me on LinkedIn or drop me a DM. I’d love to hear from you.