AsciiDoc generation from OpenAPI 2 schema omits fields with union types

[LiamClarkeNZ]

After noting rather crucial fields for ProducerRecord (key and value) were not present in the Kafka Bridge documentation, I did some digging into why they're being omitted when the documentation is generated.

Basically, it boils down to an issue with Swagger/OpenAPI < 3.1.0 - while the spec states that it reuses JSON Schema Core, the project team made a design decision (to better support codegen) that a property's type must be a string representing a single type - it cannot be an array of types (e.g., "property-foo": { "type" : ["string", "number"] }, despite this being valid JSON Schema.

When the documentation is generated, the SwaggerParser silently omits properties in a schema that it considers invalid, this leads to any properties defined with union types being omitted from the documentation.

This issue only affects two definitions:

• ProducerRecord
• ProducerRecordToPartition

Possible solutions I've looked into, none of which are great

1. OpenAPI 3.1.0 (released February 2021) does allow for union types using the JSON Schema array syntax.

   But, the dependency chain to use this to generate docs is long and in places brittle - strimzi-kafka-bridge uses swagger2markup-maven-plugin, which wraps swagger2markup, which relies on code from swagger-core, especially the parser.

   Swagger-core's parser does not yet support OpenAPI 3.1.0, but when it does, swagger2markup may not be able to utilise it for some time, as the project was stagnant for a long period following the core developer having to leave it. Work on it has picked up again, but OpenAPI 3 support is still very much a WIP, and is only available from snapshot builds from main. In the course of this investigation, I found one bug in the OpenAPI v3 support in swagger2markup that throws an exception and dies when parsing schema where a field is optional.

   Also, getting onto the correct code path to actually use the existing v3 support would require code changes in the Maven plugin and careful usage of entrypoints - e.g., passing a java.nio.Path pointing to the OpenAPI schema to the Converter's from method will lead down the OpenAPI v2 code path, but passing a java.io.Reader pointing to the same file path (represented as a string) will allow usage of the OpenAPI v3 code path.

   Then the Maven plugin would need to use a later release or snapshot to provide 3.1.0 support.

2. Generate docs from openapi.json instead of openapiv2.json, after fixing the bug described above, and entering the converter the right way, and forcing the working version into the Maven plugin's dependencies (or writing a new plugin). This does include the affected fields, but it is limited in that it's unable to derive the field type from the valid oneOf construct used in openapi.json, so leaves the schema field blank. A temporary workaround could be to include the possible types for the field in the description.

3. Post-process and patch the generated AsciiDoc to fix the two entities affected - this is yet another workaround while waiting for OpenAPI 3.1.0 to be supported by all dependencies in the chain, and would not stop entities that have their schema updated to include a union type from suffering the same issue.

So, that's the issue. Unfortunately I don't have any great ideas on fixing it.