# Vibe.Text.Json.OpenApi

Description

This library parses an OpenApi document into a class structure, ready to be used, most commonly by code generators. It currently only officially supports OpenApi 3.0.3, although other versions may work.

Process

This library has proved to be very tricky to get perfect, as we need to support lots of different things, and we've built a large complex schema before completing this parser. As such, sections of this library have been recently rewritten to improve stability, and support new features such as self-referential types.

The problem is, OpenApiSchema can hold a multitude of different things - anything from simple base types such as 'string', to named models, anonymous objects, and concepts such as "any of". These must be referenced in such a way that we do not parse the same schema twice, or we get problems with stack overflows. Essentially this is a catch 22 situation where until we parse the object we can't cross reference it, but when we parse it it might need to be a reference instead.

Schemas

Most of the problems with the current feature set relate to schemas - other types such as responses we largely do not use the references system, and certainly not cyclic references. However, whatever the solution for schemas is will probably roll out across the other object types and provide support.

Some points to bear in mind:

• The collections may need to be processed seperately. i.e. AllOf applies directly to interface based multiple inheritance.
• We must resolve all of the components/schemas as a first step, ignoring the fact they have references attached.
• From then on, any schema which is a reference should be retrieved from the cache.
• SCHEMAS RETRIEVED FROM THE CACHE MUST NOT BE RESOLVED
• It may be worth keeping the schema fairly closely matched to the native impl, and adding a Code object with the resolved names in, to avoid misuse and confusion.
• When processing the Code object for a schema, objects within the AllOf collection should have their properties gathered and lifted back to the parent.
• Ideally, objects within the properties should be captured as a nested type.
• Enum values should be captured for the code generator
• Required flag should be respected on properties I assume via Nullable
• Supporting the other reference types shouldn't be hard. Try including seperate files and linking to it.
• Should be able to detect the format and load it - or do we preload all files into the cache?
• Preloading seems better but we will have to deal with the mismatches in the ReferenceV3

Stages

1. Walk through all of the schemas in document, wrapping them in our class and storing them in a dictionary. It's still not clear which type we're using as a key.
2. Walk through all of these schemas, and extract the data to handle the name, handle, type info etc.
3. Step through the child schemas for each collecion type, i.e.