Document JSON-Overlay framework, consider extracting to separate project

[tedepstein]

The API and Object Model Overview topic currently has a broken link to https://github.com/RepreZen/KaiZen-OpenApi-Parser/blob/master/json-overlay-framework, which doesn't exist yet. The section at the end indicates that more information on JSON Overlay will be added, so this issue serves as a placeholder for that work.

Separately, we've talked about maybe extracting JSON Overlay to its own project, so that's noted here as well for future consideration.

[emrul]

Same page also states: " schema.isPropertyReference(String name) - true if the schema for the indicated property is specified by a reference.

schema.getPropertyReference(String name) - retrieve the Reference object for the reference."

However, those 2 methods don't appear to exist (I may be mistaken but I've spent some hours checking). I guess some refactoring has happened and the docs are now not in sync with the code?

[andylowry]

@emrul Yes, sorry. Will try to update the docs shortly. The reference information is now no longer part of the generated API. It and several other methods relating to the implementation rather than to the modeled data were causing the APIs to appear very polluted. And the approach also didn't provide full access to all reference information.

All this stuff has instead been moved to a new adapter class called Overlay. So e.g. you can say Overlay.of(schema).isReference(name), and likewise for getReference().