Support overriding description of $ref as part of OpenAPI 3.1

[patricksamson]

Hello,

I'm trying to add linting to large OpenAPI 3.1 files and and got many no-$ref-siblings errors because we often override the description to add more details.

Since this was supported by some tools and not others I started digging a bit more into what the standard actually is.

It seems that starting with OpenAPI 3.1, it is possible to override the description and summary of a reference, but ONLY those two fields.
Here's a link to the relevant part of the spec : https://spec.openapis.org/oas/v3.1.0#reference-object
And a relevant issue on the OpenAPI-Specifcation repo confirming this behaviour : OAI/OpenAPI-Specification#2744

Here's a quick a example that works if you paste it in https://editor-next.swagger.io, and stops working when setting the OpenAPI version to 3.0.0 :

openapi: 3.1.0
info:
  title: Demo
  version: 1.0.0

components:
  schemas:
    Order:
      description: An Order
      type: object
      properties:
        id:
          type: integer
        customer:
          description: A happy customer
          $ref: "#/components/schemas/Customer"

    Customer:
      description: A Customer
      type: object
      properties:
        id:
          type: integer

[daveshanley]

Cool, will add it to the list!

[LasneF]

a "recent" page explaining the $ref model in details has been published by OpenAPI initiative there
https://learn.openapis.org/referencing/overview.html and around how to resolve reference

[mchlumsky]

FastAPI, a popular rest API framework started generating OpenAPI specs that trigger no-$ref-siblings.

Even their testing would trigger that rule.