Skip to content

Document OpenAPI 3.2 support - #7436

Draft
brandonmcconnell wants to merge 5 commits into
mainfrom
cursor/eng-11064-openapi-3-2-docs-9943
Draft

brandonmcconnell wants to merge 5 commits into
mainfrom
cursor/eng-11064-openapi-3-2-docs-9943

Conversation

@brandonmcconnell

@brandonmcconnell brandonmcconnell commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Documentation changes

Adds an OpenAPI 3.2 features section to api-playground/openapi-setup.mdx and updates the supported-version statements to include 3.2. Covers tag hierarchies, query and additionalOperations (including the frontmatter form for custom methods), in: querystring, itemSchema streaming, dataValue / serializedValue, device authorization and other security scheme additions, defaultMapping, serialization rules (style: cookie, allowReserved, positional encodings), document-level fields ($self, servers[].name, response summary, components.mediaTypes), and the documented limitations from the coverage matrix in mint#11562.

Hold until the mint stack has merged and the server has picked up the published packages. There is no feature flag: 3.2 documents are accepted by their declared version once the mint stack (#11550 → #11562) and server#8382 are deployed; merging this earlier would document behavior customers cannot yet use. Features that merge later in the stack can be documented incrementally if the stack lands in pieces.

Closes ENG-11064 (docs portion)


For Reviewers

When reviewing documentation PRs, please consider:

✅ Technical accuracy

  • Code examples work as written (each YAML/MDX snippet mirrors a fixture in the mint stack's tests)
  • Commands and configurations are correct
  • Links resolve to the right destinations
  • Prerequisites and requirements are accurate

✅ Clarity and completeness

  • Instructions are clear and easy to follow
  • Steps are in logical order
  • Nothing important is missing
  • Examples help illustrate the concepts

✅ User experience

  • A new user could follow these docs successfully
  • Common gotchas or edge cases are addressed (Limitations subsection)
  • Error messages or troubleshooting guidance is helpful
Open in Web Open in Cursor 

Co-authored-by: Brandon McConnell <brandon@dreamthinkbuild.com>
@mintlify

mintlify Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
mintlify 🟢 Ready View Preview Oct 2, 2026, 2:12 AM

Co-authored-by: Brandon McConnell <brandon@dreamthinkbuild.com>
Co-authored-by: Brandon McConnell <brandon@dreamthinkbuild.com>
@cursor

cursor Bot commented Sep 25, 2026

Copy link
Copy Markdown

@greptileai
/devin review
bugbot run

Re-review requested: prior findings were addressed in follow-up commits.

@cursor

cursor Bot commented Sep 26, 2026

Copy link
Copy Markdown

/devin review
bugbot run
@greptileai

…for-byte behavior

Co-authored-by: Brandon McConnell <brandon@dreamthinkbuild.com>
…fields are accepted without checks

Co-authored-by: Brandon McConnell <brandon@dreamthinkbuild.com>

This branch was successfully deployed

1 active deployment
staging — 0c6e034d Deployed Oct 2, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants