Only primitive component fields retain their doc comments

[oliver-impero]

For some reason (bug?), only primitive component fields seem to retain their doc comments (but not fields that are custom types/newtypes), e.g.:

Code
Screenshot of Swagger UI

[juhaku]

Yes that is not actually bug but unimplemented by desing. Since OpenAPI 3.0 version does not have description or summary in fields which are references to another components. See here https://swagger.io/specification/#reference-object. For each type having field of Component the OpenAPI represents them as a $ref which does not have the aforementioned values.

However OpenAPI 3.1 spec does have these values withing the reference object (https://spec.openapis.org/oas/latest.html#reference-object). This is something that could be supported future since currently it follows the OpenAPI 3.0 spec as much as possible.

[oliver-impero]

Hm, that's very unfortunate. Would it be possible to enable it via a feature flag, like openapi-3.1-preview?
That would be great :)

[juhaku]

Hm, that's very unfortunate. Would it be possible to enable it via a feature flag, like openapi-3.1-preview? That would be great :)

Yes, it could be added, only thing is to see whether the Swagger UI will support it as well. It actyally has been my plan to support 3.0 and 3.1 versions but not been the priority since there are still more important things to get out of the way first. But if that comforts at all this could be done in not too distant future. :) Along with this the feature flag should also take care that other 3.1 version related properties work as well as expected.

[oliver-impero]

But if that comforts at all this could be done in not too distant future. :)

Thanks, that would be great! :)
IMHO it's quite an important thing to have comments for all fields, because a type's doc is not enough: It doesn't say anything about the role it plays at each occurrence (where the type is used for a field).

[juhaku]

But if that comforts at all this could be done in not too distant future. :)

Thanks, that would be great! :) IMHO it's quite an important thing to have comments for all fields, because a type's doc is not enough: It doesn't say anything about the role it plays at each occurrence (where the type is used for a field).

Yeah I agree.. Sorry for late reply I have been recently really busy and thus I have had no time to invest to the library at all.

[oliver-impero]

@juhaku Is there a way to contact you for sponsoring your work on certain issues, like the comments for all fields? This issue is quite important for us :)

[juhaku]

@oliver-impero Unfortunately not at the moment, I haven't fully set it up, My original goal was to have the github sponsors up and runnig but haven't finalized the setup. I need the get it done in the near future indeed. But but I can take a look at this after I fix #132 :)

But in a long run, of course all sponsorships and support and contributions are welcome and will help to advance the library to become even more awesome :) And especially sponsorships would give me bigger reason to prioritize some of the work over the others.

[juhaku]

Getting back to this I tried this out with editor.swagger.io only to find out that Swagger UI is unable to render OpenAPI version greater than 3.0.x. So 3.1.x is not supported by Swagger UI. And even if the description were to be added the the $ref object as shown below, it will be ignored by the Swagger UI and lint warning will be emitted to the user.

{
  "$ref": "#/schemas/components/Item",
  "description": "This is custom description"
}

Lint warning suggest that aforementioned type would be wrapped with allOf type as shown below

{
  "allOf": [
    "$ref": "#/schemas/components/Item",
    "description": "This is custom description for the Item"
  ]
}

This way Swagger UI is able to override shown description for the referenced type, but currently this behaviour is not supported. The description still won't render as a field description but instead will override the component description for the field. Drawback of this implementation is that Swagger UI will loose the type definition of the field since the above example actually creates a new anonymous object which is combination of the $ref and the description.

Implementing this functionality needs some designing and changes to existing behaviour. Also this would only consern OpenAPI 3.0.x and would not be the case with the 3.1 which also adds complexity.

[juhaku]

Closing due inactivity.

[kyldvs]

Can this issue be re-opened? I'm running into this same issue where I can't add a description to $ref types, any sort of workaround would be great.

(Or perhaps this is dependent on 3.1 support in #531 ?)

[juhaku]

(Or perhaps this is dependent on 3.1 support in #531 ?)

This actually is dependant to OpenAPI 3.1 support. 3.0 there is no way to this. Whenever the 3.1 support will come this will naturally be supported as well. Thus no separate issue is needed IMO.