play-swagger
play-swagger copied to clipboard
iheartradio
default tag "routes" is confusing
if there is no include, all the endpoints got a tag "routes" and will be collapsed when swagger UI loads. This is a bit confusing.
Just ran into this issue the other day. I would note that this tag also appears when you have a route in the main routes file but with another tag. For example, I have a tag "game" and if I have a route in my main routes file tagged "game", the "routes" tag also appears despite there being no routes with that tag, even if there are other includes in the routes file.
Instead, if I force all of my routes to be in an external routes file, the "routes" tag disappears. This is not a very convenient solution as I have to split my routes files even if I don't need them that way. A good solution might be checking if there are any untagged routes and, if there are none, removing the "routes" tag altogether.
yes please, remove the routes tag if there are no paths in it. All my paths are under different tags, and I have a couple of NoDocs routes, but the routes tag still shows, empty.
Is there any eta on this being solved? I am currently still experiencing this issue which indeed is confusing.
Possible fix would be to remove this code here
generatedTagsJson adds a global level tag for every routes file processed. The same tag is already added to all routes in the file, so the global level tag is not required (and, imo, does not add any information to the doc). If users need to add description or other attribute, those can always be added in the base swagger file.
Removing this could fix the issue.
cc: @joprice , @kailuowang
I think that is just an inventory of all the tags. I suspect that removing it might break all tags and not fix the root tag problem. Maybe you can write some test to try it out.
@kailuowang , As defined in swagger docs:
Note that it is possible to use a tag in an operation even if it is not defined on the root level.
The root tags object is for adding common attributes to a tag like description. The play swagger plugin adds a tag to all routes regardless of what's in the root tag object. Here's my test for the same.