search

iheartradio / play-swagger

Swagger spec generator for play framework
Apache License 2.0
403 stars 131 forks source link

Definitions description based on Scaladoc #498

Closed Javakky-pxv closed 2 years ago

Javakky-pxv commented 2 years ago

OpenAPI allows you to specify a description for the parameter object. Since play-swagger often generates types from Scala code, overriding description from routes files or swagger.json is very cumbersome. Besides, it feels more natural to have the meaning of the type variables described in the documentation comments.

Scaladoc information can be obtained as runtime annotations by having runtime-scaladoc-reader added to the user's project. It can be parsed by ScaladocParser in the scala meta, so it looks like it could be implemented if you try hard enough.

To be honest, I would prefer to parse comments from code files like scalafix and others, but the current implementation does not seem to do so in order to benefit from the play system.

Javakky-pxv commented 2 years ago

@kailuowang Please, advise. It's a feature I'd like to have, but I'm wondering if it's a good idea to encourage users to install another compiler plugin. Have you considered this feature in the past? And do you prefer this policy?

kailuowang commented 2 years ago

@kailuowang Please, advise. It's a feature I'd like to have, but I'm wondering if it's a good idea to encourage users to install another compiler plugin. Have you considered this feature in the past? And do you prefer this policy?

We thought about this. I don't feel super enthusiastic about this feature. It could be more convenient. But it also makes it necessary for the user to be very careful writing scaladoc comments in their code because it's automatically exposed to the API doc which is open. Usually scaladoc is for internal dev consumption only, while open API doc has a more open access. Play-swagger generates docs with information already available to the API consumer, i.e. field name and types. Scaladoc, on the other hand, is never available to API consumers. I think fundamentally, scaladoc and swagger API specification are two different docs that serve different purposes and audiences. There are some overlaps and duplications, but using the same text for both might be risky. That being said, If this can be an opt-in feature, I think some users can benefit from it as long as they understand the caveats.