You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
From the openapi-style-validator project, we have an issue with properties of type string and format byte where the example is not read: OpenAPITools/openapi-style-validator#132
@gervaisb thanks for reporting this. It is a bit tricky and has been addressed in #1682, and will be available in next release.
TLDR
Probably in your case the best option is to set either system property or env variable swaggerParserBinaryAsString to any non null value. This will result in parser deserializing schemas with type=string and format=binary or format=byte as StringSchema` instances, and string provided in example will be available as is.
Short background
Swagger Core "models" - also for historical reasons - provides a hierarchy of classes representing Json Schema constructs; depending on type and format, Swagger Parser deserializes schemas into one of these classes, which define types to be used for fields like default, enum, etc, including example. If the data type is different, like in ByteArraySchema just updated in scope of this ticket, the value is converted (if possible) into the target datatype. In this case the example: whateverbinarystring would be converted into a byte array (via value.toString().getBytes(), opinionated, an alternative could be considering the value be Base64 encoded). During serialization (handled by swagger-core / Jackson) this binary value is serialized differently in Json (converted to string) and YAML (using YAML tag to represent binary). which might result in inconsistent/wrong behaviour.
Given that there is not much added value in using specialized classes ByteArraySchema and BinarySchema, as mentioned above #1682 introduces option to deserialize into a StringSchema, which provides a more consistent behaviour. Option is not activated by default for backward compatibility
we have added indeed such conversion in swagger-api/swagger-core#4147, therefore you can use it if it fits your needs (by using parser "as is" , with no swaggerParserBinaryAsString property/env set).
The first possible issue with this approach is that the conversion / data binding is opinionated, as it uses getBytes() to encode the string into bytes, while e.g. the serialized string could be meant to be a Base64 encoded representation of the bytes (Jackson e.g. uses Base64 for default binding of string to byte[])
Another issue is serialization of the parsed string, in this case the serialized value will be encoded in Base64, resulting in a different string from the one parsed.
We might choose to try using Base64 in the cast method above, but again this would be an opinionated choice, given also that e.g. example is of any type in OAS 3.0, possibly including any encoding/representation of binary values
An additional issue is serialization to YAML; YAML is capable to represent binary using tags, and indeed default serialization uses that, therefore a YAML version of the same spec, with the same string value in example as the one in JSON version, would not be parsed correctly (would actually break).
example: !!binary |-Y2FjY2E=
We could further address the points above by e.g. providing more options and addressing the different cases, but on top of adding quite some complexity and being not trivial, the expected behaviour would be dependent on the specific spec.
Activity
gervaisb commentedon Nov 30, 2021
After digging into the parser, I see that the value is skipped in this part of the code:
io/swagger/v3/oas/models/media/ByteArraySchema.java:50
The value is not null but is a
Stringnot abyte[]then the method returnsnullwhich is set asexamplevalue.acabarbaye commentedon Feb 28, 2022
same seems to be true with
format: binaryhttps://github.com/swagger-api/swagger-core/blob/438230d79d4597d6b703437a03c32cdbf8a28ba5/modules/swagger-models/src/main/java/io/swagger/v3/oas/models/media/BinarySchema.java#L50refs #1630 - add option to deserialize byte/binary schemas as StringS…
frantuma commentedon Mar 23, 2022
@gervaisb thanks for reporting this. It is a bit tricky and has been addressed in #1682, and will be available in next release.
TLDR
Probably in your case the best option is to set either system property or env variable
swaggerParserBinaryAsStringto any non null value. This will result in parser deserializing schemas withtype=stringandformat=binaryorformat=byteasStringSchema` instances, and string provided in example will be available as is.Short background
Swagger Core "models" - also for historical reasons - provides a hierarchy of classes representing Json Schema constructs; depending on
typeandformat, Swagger Parser deserializes schemas into one of these classes, which define types to be used for fields likedefault,enum, etc, includingexample. If the data type is different, like inByteArraySchemajust updated in scope of this ticket, the value is converted (if possible) into the target datatype. In this case theexample: whateverbinarystringwould be converted into a byte array (viavalue.toString().getBytes(), opinionated, an alternative could be considering the value be Base64 encoded). During serialization (handled by swagger-core / Jackson) this binary value is serialized differently in Json (converted to string) and YAML (using YAML tag to represent binary). which might result in inconsistent/wrong behaviour.Given that there is not much added value in using specialized classes
ByteArraySchemaandBinarySchema, as mentioned above #1682 introduces option to deserialize into a StringSchema, which provides a more consistent behaviour. Option is not activated by default for backward compatibilitygracekarina commentedon Mar 23, 2022
refs: swagger-api/swagger-core#4147
gervaisb commentedon Mar 23, 2022
Thanks @frantuma for the explanation. I am just wondering why you can't try the conversion from the
ByteArraySchemaclass itself?frantuma commentedon Mar 28, 2022
@gervaisb
we have added indeed such conversion in swagger-api/swagger-core#4147, therefore you can use it if it fits your needs (by using parser "as is" , with no
swaggerParserBinaryAsStringproperty/env set).The first possible issue with this approach is that the conversion / data binding is opinionated, as it uses
getBytes()to encode the string into bytes, while e.g. the serialized string could be meant to be a Base64 encoded representation of the bytes (Jackson e.g. uses Base64 for default binding ofstringtobyte[])Another issue is serialization of the parsed string, in this case the serialized value will be encoded in Base64, resulting in a different string from the one parsed.
We might choose to try using Base64 in the
castmethod above, but again this would be an opinionated choice, given also that e.g.exampleis ofanytype in OAS 3.0, possibly including any encoding/representation of binary valuesAn additional issue is serialization to
YAML; YAML is capable to represent binary using tags, and indeed default serialization uses that, therefore a YAML version of the same spec, with the same string value in example as the one in JSON version, would not be parsed correctly (would actually break).We could further address the points above by e.g. providing more options and addressing the different cases, but on top of adding quite some complexity and being not trivial, the expected behaviour would be dependent on the specific spec.
gervaisb commentedon Mar 29, 2022
Thanks for your work. Any idea when it will be released?
frantuma commentedon Mar 29, 2022
no fixed ETA but probably within first week of April