Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Only primitive component fields retain their doc comments #137

Closed
oliver-impero opened this issue May 11, 2022 · 11 comments
Closed

Only primitive component fields retain their doc comments #137

oliver-impero opened this issue May 11, 2022 · 11 comments

Comments

@oliver-impero
Copy link

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
Copy link
Owner

juhaku commented May 11, 2022

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
Copy link
Author

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
Copy link
Owner

juhaku commented May 11, 2022

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
Copy link
Author

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
Copy link
Owner

juhaku commented May 16, 2022

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
Copy link
Author

@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
Copy link
Owner

juhaku commented May 25, 2022

@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
Copy link
Owner

juhaku commented Jun 12, 2022

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
Copy link
Owner

juhaku commented Nov 3, 2022

Closing due inactivity.

@kyldvs
Copy link

kyldvs commented May 17, 2024

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
Copy link
Owner

juhaku commented May 18, 2024

(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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Archived in project
Development

No branches or pull requests

3 participants