generate schema classes for optionally provided secondary spec files

[daniel-sc]

PR checklist

• Read the contribution guidelines.
• Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh, ./bin/openapi3/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\. If contributing template-only or documentation-only changes which will change sample output, be sure to build the project first.
• Filed the PR against the correct branch: master, 4.1.x, 5.0.x. Default: master.
• Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

This allows to generate classes for (technically) unused schemas in secondary specification files using the new option --additional-schemas-input-specs - see #3257.

fixes #3257

[macjohnny]

Cc @TiFu (2017/07) @taxpon (2017/07) @sebastianhaas (2017/07) @kenisteward (2017/07) @Vrolijkx (2017/09) @macjohnny (2018/01) @nicokoenig (2018/09) @topce (2018/10)

[macjohnny]

Cc @wing328 @jmini @jimschubert

[macjohnny]

LGTM, haven't tested it

[macjohnny]

@wing328 do the docs need to be updated somewhere else in addition?

[macjohnny]

ping @wing328

[jimschubert]

I think this addition will add a lot of complexity to the generator just to support an edge case. I'd much rather guide users looking for this functionality to rerun generation against each additional spec and generate the models that way.

A main reason for this is that it'll complicate what we consider a "valid" spec. If one of these additional specs don't define a path object, they're technically invalid.

Another concern is naming conflicts. This impression will overwrite any schemas with the same name, and this can be confusing. Additionally, the parsing done by swagger-parser may not result in the expected once graph if you're referencing models across these files (better to stick to $ref).

[daniel-sc]

Hi @jimschubert,

really appreciate the feedback!

I'll try to argue the other case, as to my experience and projects I've seen, the setup as described in #3257 is often used. I agree that this might not follow 100% the intentions of the technical specs, but as many teams use this approach to split up model and paths and also use inheritance like this (at least as long oneOf is not completely supported by some (many?) generators), I'd suppose this is a rather heavily used edge case.

Would it be possible to mark this flag as "beta" so that it can be removed again, if acutal problems show up?

(Of course I'll resolve the merge conflicts, once we're somewhat sure if we want this included..)

[jimschubert]

@daniel-sc I don't disagree that there's utility in separating schemas by file. In fact, his is already supported by swagger-parser, and should work as expected. My comment above focuses on targeting multiple, potentially unrelated, spec documents.

As an example, this implementation would allow me to target petstore.json plus petstore-simple.json and petstore-invalid.json... which Pet schema would be expected in the outcome? What if two of these are version 2.0 and one is version 3.0.2? Should we do inline model resolution before or after adding supplemental models? There's a non-trivial amount of complexity that's added by trying to extend the behaviors of the specification.

There current master should generate unused models if they're referenced in the spec. Let me try the example in the open issue later to understand what's missing.

[daniel-sc]

@jimschubert Did you manage to check the example in the issue?