springwolf
[Enhancement request] support other schema formats, especially openapi schema.
Since V3, AsyncApi supports different possible schema formats to describe the payload of messages (and headers).
While application/vnd.aai.asyncapi;version=3.0.0 is the default schema format, there are some other allowed formats for payload description:
SpringWolf currently delivers AsyncApis with data schemas only in default schema format (application/vnd.aai.asyncapi;version=3.0.0). My suggestion is to provide support for alternative schema formats, beginning with application/vnd.oai.openapi;version=3.0.0 which is one format in the list of the 'recommended' schema formats an asyncapi implementation should support.
Motivation
While application/vnd.aai.asyncapi;version=3.0.0 and application/vnd.oai.openapi;version=3.0.0 are quite similar, they differ in some details, especially the format of discriminator informations for inheritance.
We do currently use openapi generator to generate java model classes from openapi and we would like to use the same generator to generate model classes from asyncapi files (extracting only the components/schemas parts). Which is currently not possible because an asyncapi schema with discriminator attributes can not be unmarshalled to a valid OpenAPI Model.
Technical details
Under the hood, SpringWolf uses currently Swagger ModelResolver and ModelConverters to generate OpenApi/Swagger Schema Models, which are then transformed to SchemaObject Types (Springwolf internal asyncapi schema implementation). So there is allready an existing routine to generate application/vnd.oai.openapi;version=3.0.0. Additionaly, SpringWolf has MultiFormatSchema class as Container for a schema-Reference and an schemaformat Field. Event the Enum SchemaFormat does exist (however openapi-schema still missing).
A possible solution introduce a new environment property for the global schema format (defaults to asyncapi-schema) and optional allowing 'openapi-schema'. On a first glance, these classes needs an update:
- SwaggerSchemaService
- SwaggerSchemaUtil (?)
- ExtractedSchemas
We would like to provide a PR for this enhancement.
Open:
- [ ] Internally, use MultiFormatSchema everywhere to reduce complexity
- [ ] Verify that non-default schemaFormat does visualize in springwolf-ui
- [ ] Decide on further usage of SchemaFormat enum
- [ ] Clean up code comments
- [ ] Optional: support non-default schemaFormat in json-schema add-on
- [x] Discussion between OpenApi 3.0 and OpenApi 3.1 in https://github.com/springwolf/springwolf-core/issues/1487
Hi @tvahrst, sounds like a good enhancement for Springwolf. At the moment we only have two questions:
- Do you want to replace one schema format with the other for the complete specification or do want to mix both formats in the same specification?
- When you say environment property, you mean SpringwolfConfigProperties.java?
We are looking forward to see the first draft PR.
Hi @sam0r040 , yes, environment property means SpringWolfConfigProperties.java (which loads its data from the spring environment).
Regarding multiple schemaformats: I would suggest to begin with a global schemaformat property which defines the schemaformat for all schemas in the current api specification. The default value remains application/vnd.aai.asyncapi;version=3.0.0 which will cause no changes to asyncapi spec.
When set to application/vnd.oai.openapi;version=3.0.0 all occurences of schemas in the spec become
Multi Format Schema Objects] with an additional schemaformat Property.
(In a future enhancement, we could introduce new annotation properties to allow the definition of custom schema formats per payload / header. )