Duplicate Tags

[jkraml]

Describe the bug
The OpenAPI specification states: "Each tag name in the list MUST be unique.". However, in certain cases you can get duplicate tags.

Springdoc appears to ensure tag uniqueness using Sets which delegate to Tag.equals which includes more fields than just name. Thus allowing duplicates if e.g. the description differs.

We encountered this while migrating from Springfox, since we declare tags on controller classes and additionally in a global configuration where we add descriptions. A stripped-down example including a fix can be seen here.

To Reproduce

• Create two controllers with @Tag(name="foo") and @Tag(name="foo", description="d")
• Open OpenAPI Description (/v3/api-docs) and inspect the tags list. It will contain two entries with name "foo":
  "tags":[{"name":"foo"},{"name":"foo","description":"d"}]
• Alternatively: declare tags programmatically (see example linked above)

Expected behavior

• Include each tag name only once in the OpenAPI Description
• Log a warning when there are duplicate tags. Trying to de-duplicate the tags would be even better.

Additional context
Swagger UI appears to only use the first/last tag it encounters. If a tag is duplicated with and without a description, you'd sometimes see the description in the UI and sometimes not, depending on the tag order in the OpenAPI Description. That is how we noticed this.

As indicated in the example linked above, it would be nice if a solution would allow using a tag on multiple controllers without having to redeclare its description every time.

[jkraml]

If I may suggest a default de-deduplication strategy: return a Tag object containing just the name. That loses all additional data, but is correct and universal.

[bnasslahsen]

@jkraml,

There are no plan for this deduplication.
The generated code, reflects your OpenAPI description.

Try correcting your OpenAPI description, or use your custom OpenApiCustomiser