OAS 3.1: Examples in the open api spec schema property should be an array

[avin-kavish]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4

Plugin version

7.3

Node.js version

16

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

20

Description

schema object in Open API spec follows the JSON Schema standard as mentioned here.

example field is deprecated as mentioned here.

examples field is an array as mentioned here in the JSON schema spec.

But, fastify-swagger generates the examples field as an object using this method convertExamplesArrayToObject, which breaks some implementations of Open API spec viewers.

Also, note, not every examples field is supposed to be an array, only when JSON schema is expected. For example, the examples of the response object are indeed an object, as mentioned here.

Steps to Reproduce

Generate open api spec when you have validation schema like,

import { Type as t } from '@sinclair/typebox'

t.String({
  examples: [ 'haha', 'haha2' ]
})

generates schema like,

schema:
  type: string
  examples:
    haha:
      value: haha
    haha2:
      value: haha2

Expected Behavior

schema:
  type: string
  examples:
      - haha
      - haha2

I think the solution would need to conditionally generate an example array in JSON Schema and an example object in other places.

[mcollina]

Thanks for reporting! Would you like to send a Pull Request to address this issue? Remember to add unit tests.

[avin-kavish]

I'm looking into opening a PR for this.

Looks like there were some related changes in #616.

Now the json schema example gets lifted up to open api example field. But, the json schema examples are still an object.

[mcollina]

cc @mxck

[mcollina]

All of you are significantly more expert than me on the OpenAPI spec. I defer to contributors on these OAS features

[mxck]

@avin-kavish doesn't swagger already support 3.1?
I redesigned the examples field in the past PR for version 3.0

[avin-kavish]

doesn't swagger already support 3.1?

I'm not sure what you mean. Do you mean this spec? https://swagger.io/specification/

[mxck]

Yes. Check this issue swagger-api/swagger-ui#5891
I don't think there's any point in making 3.1 support if it won't work in current version of swagger?

[avin-kavish]

I see. I'm not using swagger ui. I'm using @stoplightio/elements, which only works with the 3.1 standard. So I guess, I'll patch that to work with 3.0, unless you have any solution that can be done here?

[mcollina]

To clarify: OpenAPI v3.1 has some breaking changes compared to v3.0 on the examples property?

[mxck]

Yes. In the body of the issue, there are links to the deprecation of the "example" field.
In version 3.1 they tried to be compatible with JSON schema. There the examples field is an array, was object.

[mcollina]

What other differences are there between OAS 3.0 and 3.1? We should add support to OAS v3.1 too but keep the v3.0 line as-is. Would you like to give it a go?

[avin-kavish]

Would you like to give it a go?

Yes. How do you think the version should be selected? I think it could be specified as an option to the plugin or can be requested in querystring?

[mcollina]

We differentiate with an option to the plugin, check with how swagger vs oas are handled.