Create non-validating Swagger (OASv2) parser

[andylowry]

This should primarily entail the following:

• Create a types2.yaml file to specify how JSON structures should be recognized and mapped to generated classes.
• Create a class like https://github.com/RepreZen/KaiZen-OpenApi-Parser/blob/master/kaizen-openapi-parser/src/main/java/com/reprezen/kaizen/oasparser/GenOpenApi3.java to do code generation
• Create a class like https://github.com/RepreZen/KaiZen-OpenApi-Parser/blob/master/kaizen-openapi-parser/src/main/java/com/reprezen/kaizen/oasparser/OpenApi3Parser.java to parse Swagger models.

[tedepstein]

@andylowry , @vladimir-bankovic,

OpenAPI 2.0 has a JSON Schema that describes the structure of a v2 OpenAPI document. This could be a useful input, or starting point, for creating the JsonOverlay types2.yaml file.

Just keep in mind the following limitations:

• The written, human-readable OpenAPI 2.0 specification is the definitive reference. The schema is a useful artifact, but should be considered non-normative, not a part of the official spec.
• The schema only enforces a subset of the OpenAPI 2.0 rules. It's limited by the constraint vocabulary of JSON Schema, so it's only really able to enforce structural constraints, not logical constraints, and not referential integrity in Reference Objects, the Path Item Object $ref property (which is not a proper Reference Object), and name references like the ones used in Tag Object and Security Requirement Object.

[vbankovic]

@tedepstein

So starting point for types2.yaml file should be https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md ?

[andylowry]

@tedepstein @vbankovic

Ted wrote:

OpenAPI 2.0 has a JSON Schema that describes the structure of a v2 OpenAPI document. This could be a useful input, or starting point, for creating the JsonOverlay types2.yaml file.

I disagree. The schema is likely to be far more confusing than helpful. JSON Schema is a powerful way of expressing intended structure in a way that supports validation. It does not, in my opinion, express structure in a way that makes it easy to understand the structure, either by human beings or in code.

The Swagger specification, in contrast, is VERY well suited to human understanding of the structure of a model, and correlates very closely with the type declarations needed for JsonOverlay.

This is something I looked at very closely when I began this project, and I came away with a very strong sense that a schema-based approach would complicate things considerably.

There is an open issue that would permit a schema to be supplied to the parser, so the parser could validate documents prior to parsing. This could be helpful for otherwise non-validating parsers, either because the payoff for implementing comprehensive validation is low, or as a stop-gap between getting an initial non-validating parser built and completing validation. One thing we've seen very clearly is that error messages created by a schema validator can be extremely obscure, since they relate to schema constructs, not constructs in the target documents, so my opinion is that probably schema validation is something that would best be turned off once normal validation is fully supported for a given parser.

[tedepstein]

I didn't mean to suggest that we process the schema as a replacement for the types file, or that we use schema validation as a substitute for a validator class.

I only meant that the schema represents a first pass at translating the human-readable spec into a structured, machine-readable form. So translating from the schema might be a faster way to get to a rough cut of the types file.

But if you think the confusion introduced by the schema outweighs the benefit, then there's no reason to do it.

[andylowry]

@tedepstein I understood what you were suggesting. I just disagree that the schema is much of a help in understanding the intended document structure, and it would rarely be my first choice unless it were also my only choice.

My experience is that JSON schema is not very human-readable (at least not for this human :-) ). I don't think it's any coincidence that both Swagger and OpenAPI v3 schemas arrived after the specification documents were largely complete. The fact that this was true in v3 suggests that the creators of the spec did not regret the sequence in prior versions. Creating the specification as a schema would, I believe, be a very difficult undertaking. And of course, many of the important requirements would not be captured, since JSON Schema is incapable of capturing semantic requirements.

That said, @vbankovic if the schema seems more appealing to you than the formatted spec, by all means go with that.