Rendering "unused" tags in a different way

[newgene]

OpenAPI specs provide top-level "tags" to list all relevant tags to the API. Some of the tags can be used by each OperationObject to group operations. And it's also common that some tags are not used by any operation. In these cases, I think the rendering of these tags in the current swagger-ui is not ideal, because it shows an empty dropdown for each of "unused" tags, and users have to click to know whether it is empty or not.

Here is an example: http://petstore.swagger.io/?url=http://smart-api.info/api/metadata/c806f9a29e61e08a333260ee27a7d7e4#/ontology

One possible solution would be to render "unused" tags as the "typical" tag visualization, e.g. like how "topics" rendered for a github repo. And only render those "used" tags like the way it is right now.

[webron]

Why would you define unused tags? Tags are meant for operation grouping. If you don't assign them to any operation, don't define them at all.

[newgene]

Hmm, these are just general descriptive tag applicable for the API as the whole, not necessary for an individual operation. Is "tags" field there only for the purpose of grouping operations?

[webron]

Pretty much - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#tagObject.

[newgene]

If that's the designed purpose, it's fine then. Maybe for the usability, an empty tag dropdown should disable the expansion and remove the ">" at the end? That way users don't have to click to know a tag dropbox is empty. Ideally, we should expect all "tags" are the "used" ones, but there is no enforcement in the OA specs. For the context, we are developing a domain-specific API registry, it's not uncommon to see users submit "valid" API metadata like that. It's just a bit annoying for the swagger-ui end-users when "unused" tags do exist.

[taddygrrr]

In previous 3.x versions of swagger-ui, unused/unassigned tags were not rendered. This seems like a more reasonable default behavior. I agree the tags shouldn't be there if they're not used, but that doesn't seem like a good argument for the current default behavior.

Aside: why are unused tags in the spec? For me, spec is published dynamically from java annotations by a tool (springfox); it auto-generates tags for each API container (controller). If you regroup by manually tagging APIs with java annotations, APIs are rendered only under the attached tags. I'll file an issue with springfox.

[gt-tech]

I am also running into this. We have a yaml specification file that we feed to swagger codegen plugin to generate spring boot related artifacts. To codegen plugin, we state interfaceOnly as true so codegen plugin can be fired with every maven build in generate-sources phase, however implementation of these interfaces is in hands of developer by writing concrete impl classes. What this does is to Docket is that we see two tags on finally rendered swagger ui - one thats coming out of interface and rightly since it got generated from yaml file but then also from developer inplemented controller of that impl which is bad ... not sure if this narrative is clear enough but i can share a small sample if that helps (unfortunately cant share the exact api sample so will have to muster a small pilot quickly), in all springfox swagger is treating interface generated from codegen and then actual controller impl for that interface differently

[Kamilll]

We follow the same approach as colleague from comment above. Even with custom mustache template (that doesn't include @Api annotation on java interfaces) the tags are eventually present in swagger-ui. Can somebody point me to the class responsible for creating these generic tags (they all ends with "-controller")?

[newgene]

@Kamilll we ended up hiding the empty tags in our swagger-ui instance this way:

https://github.com/SmartAPI/smartAPI/blob/d82d86b11ebd3f1f86356e64170cb5a2245ff1ce/src/templates/smartapi-ui.html#L46

Hope it's useful...