ApiDOM Bundling

[char0n]

This ticket is about bundling support in ApiDOM. There will be specialized strategies for every specification and probably it's version (if's it's breaking). This issue needs additional research and technical design.

Dereferencing vs Bundling

We only do dereference. The difference between bundling and dereferencing is that dereference resolves the documents and create a compound OAS document represented in memory possibly containing cycles. Cannot be serialized.

Bundling is a process where we resolve all the external documents and create a one compound document with only internal refs without any cycles. Can be serialized.

Resources:

• https://github.com/OAI/OpenAPI-Specification/issues/2685
• https://json-schema.org/blog/posts/bundling-json-schema-compound-documents
• JSON Schema Bunding implementation
• https://github.com/swagger-api/swagger-parser/blob/138687c5385556a648ed2a14528f522670242f99/modules/swagger-parser-v3/src/main/java/io/swagger/v3/parser/util/RefUtils.java#L29 (naming + conflict resolution in swagger-java)
• https://github.com/swagger-api/swagger-parser/blob/ebdcdcbcdd6ff3d58a22013967b3cea521f6499c/modules/swagger-parser-v3/src/main/java/io/swagger/v3/parser/processors/ExternalRefProcessor.java#L51 (naming + conflict resolution in swagger-java)

[char0n]

We need to restart this effort asap because of the OpenAPI 3.1.0 -> OpenAPI 3.0.3 downgrader. The first thing we need to do is to prepare the code infrastructure of apidom-reference for budle feature. This work doesn't include any particular bundling strategy implementation.

Next step would be to implement OpenAPI 3.1.0 bundling strategy.

TODO:

• [x] consolidate error hierarchies
• [x] create bundling infra code
• [x] create OpenAPI 3.1.0 bundle strategy
• [ ] create issues to implement bundle strategy for every supported spec