[OpenAPI 3.1] Phase 1: 3.0→3.1 converter

Open
#949 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 5 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
38/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
java, openapi
Domain
tooling

Research direction

Start from the plan in #942, then look at how org.openapitools.openapidiff.core currently parses specs and where swagger-core's mapper and JsonSchema are already used. The new normalize package must walk components, parameters, headers, bodies, callbacks and nested schemas, applying the listed rules on a deep copy. Compare converted 3.0 output against natively parsed 3.1 for the paired fixtures under the test resources as serialized JSON; also add the Swagger 2.0 fixture and a test asserting the input objects are unchanged.

Written by the indexing model from the issue text.

Description

OpenAPI 3.1.0 Support

Part of the OpenAPI 3.1 plan: #942 (Stage 1, Phase 1)

Goal

A converter that turns Swagger 2.0 / OpenAPI 3.0 objects into the 3.1 form. Not wired in yet.

Scope
  • New package org.openapitools.openapidiff.core.normalize, called once per spec
  • Walks every schema: components, parameters, headers, request/response bodies, callbacks, and nested (properties, items, additionalProperties, allOf/anyOf/oneOf, not)
  • Rules: type → types; nullable: true → "null" in types (not when there is no type); boolean exclusiveMinimum/Maximum → numeric; example → examples; typed classes → JsonSchema
  • Works on a copy (JSON round-trip with swagger-core's mapper), so the input objects are never modified
Done when
  • Converted 3.0 == natively parsed 3.1 (compared as serialized JSON) for all paired fixtures
  • Swagger 2.0 fixture converts correctly
  • Copy test: input objects are unchanged after conversion
Dominant language
Java
Stars
1.1k
Forks
191
Avg merge
4d 23h
Merged PRs (30d)
1

Getting set up

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.

More from OpenAPITools/openapi-diff

All issues in OpenAPITools/openapi-diff

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.