Redocly / Redocly/redoc

Support OpenAPI 3.2.0 documents (standalone mode)

Open
#2,773 1 comment 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Describe the problem to be solved

The OpenAPI 3.2.0 specification was released in September 2025. When loading an OpenAPI
3.2.0 document, Redoc rejects it with: "Unsupported OpenAPI version: 3.2.0". This blocks any project that has upgraded its API
contract to OAS 3.2 from rendering documentation with Redoc.

Describe the solution you'd like

Redoc should parse and render OpenAPI 3.2.0 documents the same way it handles 3.0.x and 3.1.x today. Since 3.2 is a minor
increment over 3.1, the core rendering logic should require minimal changes — the main blocker appears to be the version
validation check.

At minimum:

  • Accept openapi: 3.2.x in the version check
  • Handle any new 3.2-specific constructs gracefully (degrade rather than error if not yet fully supported)

Describe alternatives you've considered

  • Downgrading the spec to 3.1.0 — works but prevents using 3.2 features and forces contract divergence from the source of
    truth.
  • Using Swagger UI — supports 3.2 but lacks the single-page rendering and customization that Redoc provides.
  • Using Redocly CLI preview — the CLI has started adding 3.2 support, but redoc itself does not benefit from it yet.

Additional context

  • Related: #2746
  • The redocly-cli has begun incremental 3.2 support (see referenced PRs), but redoc hasn't received these changes yet.
  • OAS 3.2 is largely backwards-compatible with 3.1, so a pragmatic first step could be relaxing the version gate to 3.2.x
    while progressively adding full support.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the version validation used when loading OpenAPI documents and review how 3.0.x and 3.1.x documents are handled. Check the existing document-loading and rendering tests, then verify that 3.2.x is accepted and that unsupported 3.2-specific constructs degrade gracefully instead of causing an error.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.