Schema example should not auto convert to examples

[dhoffer]

In our upgrade from Swagger libraries to smallrye openapi it is converting all our 'example' to 'examples' in the OpenAPI schema.

This is not desirable as we need to be able provide an example that matches the data type. We use arrays extensively and even double arrays occasionally. With smallrye openapi wrapping the example in another array, will be very confusing for users.

I understand the microprofile-openapi-api has:

A free-form property to include an example of an instance for this schema.
Deprecated: use examples()
@Deprecated(since = "4.0") String example() default "";

But for now, example and examples are both valid per the OpenAPI spec.

https://github.com/oai/openapi-specification/blob/main/versions/3.1.0.md#schema-object

Deprecated: The example property has been deprecated in favor of the JSON Schema examples keyword. Use of example is discouraged, and later versions of this specification may remove it.

I would like to see smallrye openapi support example until it is actually removed which may never happen. And also support examples.

[MikeEdgar]

@Azquelt do you have any thoughts on this request? I suppose it would be simple enough to keep example and examples separated.

FYI @michalvavrik. I remember you mentioned some impact to testing around the change from example: any to examples: [].

[michalvavrik]

FYI @michalvavrik. I remember you mentioned some impact to testing around the change from example: any to examples: [].

yes, this issue describes exactly what I meant, I didn't realize it was only deprecated; I need to be more careful next time

[MikeEdgar]

Well, it is deprecated, but the scanner currently combines them all into the array, whether an example is in example or examples on the @Schema annotation. The ask is to map them without combining.

[dhoffer]

Yes exactly we think you should support both example and examples but don't combine them.

[MikeEdgar]

The current behavior may be enforced by the MicroProfile OpenAPI 4.0.2 TCK test suite (I only glanced at it). If that's a case and it's agreed that it should be changed, this will need to be changed there first.

[MikeEdgar]

Related issue in MicroProfile OpenAPI: eclipse/microprofile-open-api#674

[Azquelt]

There's not a 1:1 mapping between the annotation and the model. IMO where something is deprecated with a complete replacement, I think we should target generating the new thing. This allows users with an existing code base to generate a good OpenAPI 3.1 document without code changes.

JSON Schema added the examples keyword, never having had example. The example keyword came from OpenAPI and is deprecated in OpenAPI 3.1.

If someone really wants to put their examples under example instead of examples, I'd suggest either sticking with OpenAPI 3.0, or writing a filter to move the value from examples to example (and make their own decision on what to do if there's more than one).

[dhoffer]

I'm not following your first point/reason. I think libraries should code for user's 'least surprise'. We were not expecting example in the annotations to be examples in the OpenAPI model.

In OpenAPI model example and examples are both supported so users can use whichever they want and get the exact results they want. It does not help for the library to think the user wants something other than what they picked and switch to that something else.

That being said, I have coded our app to apply filtering to keep example as example but I'd prefer to take that out if the library didn't make the switch we didn't want.

Also note we can't go back to 3.0.x as we accidently set the version to 3.0.3 and lots of things did not work...so we have to stay with 3.1.

[Azquelt]

I'm not following your first point/reason. I think libraries should code for user's 'least surprise'. We were not expecting example in the annotations to be examples in the OpenAPI model.

If you're upgrading from MP OpenAPI 3.1 to 4.0, all your existing code will be using example, because examples did not exist in MP OpenAPI 3.1.

When you upgrade to MP OpenAPI 4.0, you expect to get your output in OpenAPI 3.1 format. I think it would be surprising if your output used the deprecated example keyword.

While I can see how if you're coming to it fresh, it looks like example and examples in the annotation should map to example and examples in the output, that's not how it was designed. The only reason that the annotation example still exists is for backwards compatibility, so that code that was written to an older version of the API can still run on the newer version. Taking this view, it makes sense that when you take that old code and generate a new OpenAPI 3.1 document for it, you get the example out in the recommended format for OpanAPI 3.1, using the examples keyword.

[dhoffer]

I see your points. We are not too interested in if the output is in 3.0.3 or 3.1 format, our users don't care about that (they don't even know what changed). And users certainly don't know or care if we are using MP OpenAPI 3.1 or 4.0, that is an internal detail.) Users just don't want our schema example wrapped in an array and moved to examples...as that will cause lots of confusion. If at some point, example is removed then we will have to explain why we now are using examples to our users, but we hope it's never removed.

But I have a workaround for this in the filter so if you can't change it...its okay...as our workaround seems to work fine. So this is not a big issue for us.

[MikeEdgar]

As mentioned in the MicroProfile issue, we can add a flag/property to disable the merging of example into examples. The default behavior will be to continue merging them.

[dhoffer]

Oh that would be ideal, thanks!