Allow for integration in OpenAPI 3.1

[CarstenWickner]

The motivation for this enhancement is this great blog post from Phil Sturgeon, describing how OpenAPI has been a subset and a superset of JSON Schema at the same time (i.e. only parts of the JSON Schema keywords were supported, while additional ones were added on top).

With the upcoming OpenAPI version 3.1, this is supposed to change insofar as that it will be only a superset of JSON Schema Draft 2019-09 (i.e. supporting all its keywords, but adding some more on top of it).
He also advocates for the API-first approach, but that is mostly applicable to new projects and not to (big) existing ones that would've to undergo extensive (manual) refactoring to produce an appropriate OpenAPI description out of the existing codebase that doesn't have the relatively new @OpenApi annotations everywhere.

Goal

The overall goal here would be to allow for the flexible generation of an OpenAPI definition from a codebase that has little to no @OpenAPI annotations on it yet. Based on that, the existing codebase could then be automatically replaced/regenerated from the OpenAPI definition. Et voilá: welcome in the API-first world. From here on out, you can make changes directly in the OpenAPI definition and have those reflected in your code.

The migration complexity would then lie in the configuration of the jsonschema-generator to pick-up as much accurate information as possible and include it in the generated models/schemas in the OpenAPI definition to minimize the information loss. The jsonschema-generator would then only be a one-time migration tool – assuming you don't need a separate generation of JSON Schemas besides what is included in the OpenAPI definition then.

What to do?

First steps: jsonschema-generator enhancements

• Allow for the schema generation in the context of the OpenAPI format.
  • [x] Allow for multiple entry/main types to be provided one-after-the-other and only in the very end producing a common list of definitions/$defs. #84
  • [x] Allow for an alias for $defs to be provided, i.e. to allow for "$ref": "#/components/schemas/YourType" instead of the currently unchangeable "$ref": "#/$defs/YourType". #84
  • [x] Apply stricter naming rules for definition keys. #84
  • [x] Cater for additional OpenAPI attributes (like "format": "int32") to be set via standard option. #136
  • [x] Create a new jsonschema-module-swagger-2 to pick-up model/schema related information provided via the respective OpenAPI @Schema annotations (for those cases, where parts of the codebase already have them or where a separate JSON Schema is being generated). #117

Next steps: integrate with OpenAPI definition being generated (e.g. by swagger-core)

• Once all the above is done, find a way to hook into the latest swagger-core (which by then hopefully supports OpenAPI 3.1 already – right now it is still OpenAPI 3.0, based on JSON Schema Draft 4):
  • [ ] Provide a swagger ModelConverter implementation, that uses a given victools SchemaGeneratorConfig instance.
• Alternatively (if the above is too difficult/cumbersome):
  • [ ] Accept a normally produced swagger definition as input and replace the contained models/schemas, assuming there is a way to unambiguously identify the classes that Swagger had encountered in the first place.

Contributions

This is just a rough plan. I'm open to suggestions and would certainly appreciate help along the way. I feel comfortable doing the "first steps" (hoping that those would be enough), but completing the "next steps" (or whatever else would be required to achieve the overall "goal") will likely exceed the time I can dedicate to this in the next couple of months. Since OpenAPI 3.1 has not been released yet and swagger-core may also need adjustments first to support it, there doesn't seem to be any rush. For OpenAPI 3.0 it may not be worth it to invest the time necessary to workaround the larger number of differences.

[mikezerosix]

My 2c: I think this project should focus on viable tech like Jakarta & Jackson. It is good to have support for legacy stuff like Swagger, javax or the stillborn OpenAPI. I just think the main focus should be on the viable tech, not the obsolete.

[CarstenWickner]

As you can see from this being a two-year-old ticket, I'm not putting a lot of emphasis on this.

Whether Swagger/OpenAPI and the javax.validation package are (still) relevant can be argued, which we don't have to get into here. At this point, the maintenance effort for those modules is negligible, so I don't see the need to drop the support any time soon.

---

I saw that someone was replacing the schema definitions created by Swagger with ones from this library in some hand-crafted post-processing. And since Swagger is allowing for their schema generation process to be augmented. I was merely capturing the idea here, to create a ready-made adapter for this use case.

But nobody else expressed interest in this so far. I haven't done much beyond making such post-processing easier.

At this point, I don't have a particular roadmap and am mostly responding to ad-hoc requests being raised. In other words: I'm open to suggestions. 😉

[CarstenWickner]

Closing this as "Won't Do" as this idea of mine got no further feedback and it seems unrealistic that I will pursue the inclusion in the swagger context on my own.