Good reason to upgrade to openapi 3.1.x ?

[patrice-conil]

In many API specifications, we use a workaround to add a description to properties that use an object reference.
This workaround create a new class derived from the reference because it uses an "allOf" keyword.
In openapi 3.1, a new version of Reference Object has been introduced to address this initial lack.

See Reference Object in the new specification.

What is your opinion on this?

[hdamker]

@patrice-conil Your link above is going to OAS 3.0.3. I suppose you meant https://spec.openapis.org/oas/v3.1.0#reference-object instead.

[patrice-conil]

@patrice-conil Your link above is going to OAS 3.0.3. I suppose you meant https://spec.openapis.org/oas/v3.1.0#reference-object instead.

Thanks @hdamker , link fixed

[shilpa-padgaonkar]

camaraproject/WorkingGroups#260

[shilpa-padgaonkar]

Another important change in OAS3.1.x https://spec.openapis.org/oas/v3.1.0#oasWebhooks

[shilpa-padgaonkar]

https://openapi.tools/ provides a good overview of tooling support for 3.0.x vs 3.1.x

[maxl2287]

Hi,

I also recommend upgrading to 3.1.x, caused by unexpected behaviour with the "allOf" keyword for openapi-code-generators.
See camaraproject/QualityOnDemand#204 .

[jlurien]

https://openapi.tools/ provides a good overview of tooling support for 3.0.x vs 3.1.x

That is indeed the key, the lack of support of v3.1 in many tools. Currently there are already features introduced in v3.0, such as the support for "oneOf", that we are avoiding because some tools or languages don'`t work well with it. If we move to v3.1 we will have to decide which parts of v3.1 we are allowed to use.

Regarding the issue of allOf and descriptions, I have tested the new feature (https://spec.openapis.org/oas/v3.1.0#reference-object), and it seems to not work well with Redoc, and editor.swagger.io does not support v3.1 entirely.

The alternative proposed in camaraproject/QualityOnDemand#204, works well:

ObjectWithNewDescription:
  description: New description
  allOf:
    - $ref: #/components/schemas/ReferencedObject

So I wouldn't move to v3.1 just because of this.

[patrice-conil]

Hi @jlurien,
I'm not the last to complain about tooling compatibility 😄 but IMHO we need to differentiate what is not yet supported by the tools, but has a chance to be in future releases and what never will be (like multiple inheritance in most of OO languages).

I've implemented many Camara APIs, and I've never found an OAS that I can use without some rewrites to make it fit my tools or get more efficient models.

I tried using editor-next.swagger.io to manage descriptions using version 3.1.0 and it works fine. This also works in IntelliJ's latest redocly plugin.

I agree with you, on "we will have to decide which parts of v3.1 we are allowed to use", but I feel that by using version 3.0, we are making the work of OAS writers and developers more complex. Because it's simpler to write this

        applicationServerPorts:
            description: A list of single ports or port ranges on the application server
            $ref: "#/components/schemas/PortsSpec"

than that

        applicationServerPorts:
          allOf:
            - description: A list of single ports or port ranges on the application server
            - $ref: "#/components/schemas/PortsSpec"

And it's also simpler to rewrite to the following if necessary just by removing a line

        applicationServerPorts:
            $ref: "#/components/schemas/PortsSpec"

[jlurien]

I agree that the support for descriptions is better in 3.1, but if we move to that version, we move with all the implications. We have to check that all our internal tools and processes are compatible with the new version. v3.1 mostly introduce full compatibility with JSON Schema Draft 2020-12, and it allows to describe schemes with a more powerful semantics, https://json-schema.org/draft/2020-12/json-schema-validation.html.

Are we going for the full package and allow projects to use any feature in v3.1?. I don't really see the risk/benefit just for the description issue. Not sure if someone has other benefits in mind.