[REQ] Propose Feature Matrix for for Generators

[spacether]

Is your feature request related to a problem? Please describe.

It is not clear to the generator users what swagger and openapi features are supported by our generators.

Describe the solution you'd like

I propose adding a feature matrix like the one shown below.
We can run unit tests in CI which may pass or fail to generate our feature matrix.
A test passing fills int X or true to show that the feature is supported.
A test failing fills in blank or false to show that the feature is not supported.
We could include hyperlinks to the test if it exists.

Type Support

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#dataTypes

Location	Int64	Int32	string	bool
Model.param	X	X	X	X
Request.query_param	X		X	X
Request.form_param			X	X
Response.query_param	X		X	X
Response.form_param			X	X

Schema.additionalProperties

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema-object

Location	Supported
Model	X
Request.body	X
Response.data	X

This matrix could be generated from CI unit testing that we run OR locally in dev machines.

Describe alternatives you've considered

• Manual addition of this info (very error prone and can get stale)
• Automated generation of this data using uint tests (table kept up to data)
• Add feature metadata in java classes
  • How do we ensure that these stay consistent with what is in our generators and that the feature keeps working?

Additional context

This is a potential large number of new tests that we are adding but would help devs understand the differences between generators and it would help us focus our efforts on bug fixes and feature additions.

[spacether]

@jimschubert this may be redundant with your #840
but my proposal decouples our feature matrix from any java classes and instead requires that we write tests to demonstrate the features.

[spacether]

It looks like my suggestion is covered in #503

[jimschubert]

@spacether the metadata for #840 is in PR currently. Once merged, it'll require review by maintainers of each generator.

The idea is that once that metadata is in a good place, we can define a test structure which validates these features without the need to rely on spot checking sample output. For instance, if I say that a generator supports OAuth and I've defined that in metadata, I can write a test around this that requires a proof (input parameters -> generated code -> parse/evaluate generated code contains expected details). I can also warn or fail if a class defines metadata but there's no test proving out that feature.

With those in place, we can also generate a feature matrix as proposed in #503. I don't think there's a way to "decouple" metadata from generator types in a maintainable way, though. The metadata is intended to be queryable and searchable... for example if I wanted to use the CLI to list generators that support OAuth, that's not possible if you rely solely on integration style tests.

Also, I don't think it would be maintainable long term to generate tables from test code. This would require that people manually write tests and stick to some defined convention, which isn't likely to catch on. I'd much rather integration tests similar to how SBT and it's plugins work where developers provide text input and expected outputs, leaving the actual test code generic. We're not that close to this implementation yet, as it first requires my PR to be reviewed and features verified by those familiar with each language and framework.

[spacether]

This ticket is redundant and @jimschubert's description and prior tickets linked to above are a better solution.

[jimschubert]

@spacether let me know if you'd be interested in evaluating some of the above work I've mentioned. I'll try to remember to tag you in related PRs.

[spacether]

Thanks @jimschubert that sounds good. I am interested in keeping an eye on this and demonstrating it in the future on generators like the Python ones.