Description and summary properties support for referenceObject

[yehor-manzhula]

Open Api Specification 3.1.0 allows description and summary properties for referenceObject, so schema like in example is valid:

Home:
      type: object
      properties:
        home_address:
                 description: "its the home address"
                 $ref: '#/components/schemas/Address'
Office:
      type: object
      properties:
        office_address:
                 description: "its the office address"
                 $ref: '#/components/schemas/Address'

But it is not supported either by swagger-ui nor swagger-edior.

[avantipande1]

Is this issue fixed? I do not see any pull request reference in any of the issues #3419 or #4013

[yehor-manzhula]

@avantipande1 No it is not

[gcatanese]

Still not fixed I guess, I would like to have a look. @frantuma which is the branch developing OAS3.1 compatibility?

[frantuma]

@gcatanese swagger-core oas 3.1 effort has been merged into master branch (and is part of latest release). This means that a ref with description and/or summary siblings (for non JSON Schema constructs) or any sibling field (for JSON Schema) will be supported in serialization/deserialization and representation. Effort to support parsing/validaton/resolving of OAS 3.1 in swagger-parser is still ongoing.

However the original question refer to swagger-ui and swagger-editor, so possibly this ticket is misplaced, as both are javascript projects not depenent on swagger-core (this repo). Effort for OAS 3.1 support in UI and Editor is ongoing but no ETA yet.

[gcatanese]

@frantuma Thanks for letting me know, I am happy to help if there are open issues (core, parser) and you would like some help. Great effort so far!

[jackoneall]

I'm still under the impression that we can not generate $refs with descriptions using 2.2.7. I'm trying to get the swagger-gradle-plugin to generate 3.1 specs by calling ResolveTask#setOpenAPI31() but that isn't working for me. Is there a README or instructions on how to generate these if this feature is indeed supported?

[jdmmnn]

@jackoneall have you found a way to generate a description as sibling for $refs?

[jackoneall]

@jackoneall have you found a way to generate a description as sibling for $refs?

No, I have not. I've given up on the prospect so the answer won't be coming from me.

[xiaoxiangmoe]

Maybe we should also wait for https://github.com/swagger-api/swagger-core/issues/4398

Not only description field, but also deprecated field, x-* extension field should be allowed in it.