Tags with only name provided are being added to the openAPI.tags field

[Mitchell-Kovacs]

Describe the bug

• For the @Tag annotation, according to https://docs.swagger.io/swagger-core/v2.2.0/apidocs/io/swagger/v3/oas/annotations/tags/Tag.html,

When applied at method or class level, if only a name is provided, the tag will be added to operation only; if additional fields are also defined, like description or externalDocs, the Tag will also be added to openAPI.tags field

• Tags with only name defined will be added to the openAPI.tags field when they should only be added to the operation
• Occasionally, the tag with without any metadata will be selected in swagger-ui and information such as the description will not be shown

To Reproduce

• tested on spring-boot 2.6.7 and 2.5.13
• sprindoc-openapi-ui version 1.6.8
• Add the io.swagger.v3.oas.annotations.tags.Tag annotation on a class or method with only the name field populated
• Example controller:

@RestController
@Tag(name = "Hello", description = "Hello World!")
@Tag(name = "Hello")
public class HelloController {

  @GetMapping("/hello")
  public String hello() {
    return "hello world";
  }
}

• actual OpenAPI Description

{
	"openapi": "3.0.1",
	"info": {
		"title": "OpenAPI definition",
		"version": "v0"
	},
	"servers": [
		{
			"url": "http://localhost:8080",
			"description": "Generated server url"
		}
	],
	"tags": [
		{
			"name": "Hello",
			"description": "Hello World!"
		},
		{
			"name": "Hello"
		}
	],
	"paths": {
		"/hello": {
			"get": {
				"tags": [
					"Hello"
				],
				"operationId": "hello",
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"*/*": {
								"schema": {
									"type": "string"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {}
}

Expected behavior

• the Tag without description should not appear in the openAPI.tags field
• expected OpenAPI Description

{
	"openapi": "3.0.1",
	"info": {
		"title": "OpenAPI definition",
		"version": "v0"
	},
	"servers": [
		{
			"url": "http://localhost:8080",
			"description": "Generated server url"
		}
	],
	"tags": [
		{
			"name": "Hello",
			"description": "Hello World!"
		}
	],
	"paths": {
		"/hello": {
			"get": {
				"tags": [
					"Hello"
				],
				"operationId": "hello",
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"*/*": {
								"schema": {
									"type": "string"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {}
}

• see https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#tag for more examples
• this looks to be related to Duplicate Tags #1625

[bnasslahsen]

@Mitchell-Kovacs,

Using the link you have provided which refers to the official swagger-core documentation :

  @OpenAPIDefinition(
            tags = {
                    @Tag(name = "Tag 1", description = "desc 1", externalDocs = @ExternalDocumentation(description = "docs desc")),
                    @Tag(name = "Tag 2", description = "desc 2", externalDocs = @ExternalDocumentation(description = "docs desc 2")),
                    @Tag(name = "Tag 3")
            }
    )
    static class ClassWithAnnotation {..}

Would generate:

openapi: 3.0.1
tags:
- name: Tag 1
  description: desc 1
  externalDocs:
    description: docs desc
- name: Tag 2
  description: desc 2
  externalDocs:
    description: docs desc 2
- name: Tag 3

This doesn't seem what you are expecting; Right ?

[Mitchell-Kovacs]

@bnasslahsen
My understanding is tags defined in @OpenAPIDefinition#tags() should populate the tags field.
Taking a look at the full example from the same link:

@OpenAPIDefinition(tags = {
        @Tag(name = "Definition First Tag"),
        @Tag(name = "Definition Second Tag full", description = "desc definition")
})
@Tag(name = "Second Tag")
@Tag(name = "Fourth Tag Full", description = "desc class", externalDocs = @ExternalDocumentation(description = "docs desc class"))
@Tag(name = "Fifth Tag Full", description = "desc class", externalDocs = @ExternalDocumentation(description = "docs desc class"))
@Tag(name = "Sixth Tag")
public class TagsResource {

    @GET
    @Path("/")
    @Operation(tags = {"Example Tag", "Second Tag"})
    @Tag(name = "Third Tag")
    @Tag(name = "Second Tag")
    @Tag(name = "Fourth Tag Full", description = "desc", externalDocs = @ExternalDocumentation(description = "docs desc"))
    public Response getTags() {
        return Response.ok().entity("ok").build();
    }
}

Resolves into:

openapi: 3.0.1
tags:
- name: Definition First Tag
- name: Definition Second Tag full
  description: desc definition
- name: Fourth Tag Full
  description: desc
  externalDocs:
    description: docs desc
- name: Fifth Tag Full
  description: desc class
  externalDocs:
    description: docs desc class
paths:
  /:
    get:
      tags:
      - Third Tag
      - Second Tag
      - Fourth Tag Full
      - Example Tag
      - Fifth Tag Full
      - Sixth Tag
      operationId: getTags
      responses:
        default:
          description: default response

• Here we can see the tags defined in OpenApiGeneration in the openAPI.tags field (Definition First Tag, Definition Second Tag full).
• If you look at the class level tags with only the name defined Second Tag, Sixth Tag, you'll see that tags applied to the operation but not the openAPI.tags field

I see that my initial description was unclear/inaccurate, hopefully this clears up what I would expect.

[bnasslahsen]

@Mitchell-Kovacs,

I have added a first fix for it.
Don't hesitate to test it with the latest SNAPSHOT and provide your feedback.

[Mitchell-Kovacs]

The latest snapshot looks to generate as I was expecting.

Thank you, much appreciated!