swagger-api / swagger-api/swagger-parser

[Feature]: Support for OpenAPI Spec 3.2

Open
#2,248 5 comments 19 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Feature
Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

Feature Description

Add support for parsing and validating OpenAPI Specification 3.2.0. This update addresses the gap in current swagger-parser capabilities where only older OpenAPI versions are supported, preventing users from leveraging the latest specification features and improvements.

Use Case

  1. Modern API Development: Teams adopting OpenAPI 3.2.0 for new API specifications cannot use swagger-parser for validation, documentation generation, or code generation workflows
  2. Migration Projects: Organizations upgrading from older OpenAPI versions (3.0.x, 3.1.x) to 3.2.0 need tooling support to validate their migrated specifications
  3. CI/CD Pipelines: Automated API validation in deployment pipelines fails when encountering OpenAPI 3.2.0 specs, breaking development workflows
  4. Toolchain Integration: Downstream tools that rely on swagger-parser (documentation generators, mock servers, client SDK generators) cannot process 3.2.0 specs

Suggested Solution (optional)

  1. Schema Updates: Update the internal schema definitions to support OpenAPI 3.2.0 structure and validation rules
  2. Version Detection: Enhance version parsing to recognize 3.2.0 in the openapi field
  3. Backward Compatibility: Maintain support for existing OpenAPI versions while adding 3.2.0 capabilities
  4. New Feature Support: Implement support for 3.2.0 specific features such as:
    • Updated JSON Schema dialect (2020-12)
    • New webhook object support
    • Enhanced security scheme features

Alternatives Considered

Additional Context

Checklist

  • I have searched the existing issues to ensure this is not a duplicate.
  • This feature would be useful to more than just my use case.
  • I have provided enough detail for the maintainers to understand the scope of the request.

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 reading the OpenAPI 3.2.0 specification and release notes linked in the issue, then locate the parser's current version detection and internal schema definitions. Compare existing support for OpenAPI 3.0.x and 3.1.x with the 3.2.0 requirements, including the listed JSON Schema, webhook, and security changes. Done means 3.2.0 documents parse and validate while existing supported versions continue to work.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.