Are tags with different descriptions possible?

[cristalp]

We have a number of standardized tags and also standardized descriptions for them. But sometimes an endpoint should have a different tag description. Or another resource should have a different tag description.

I've created a small test:

@Path("/foo")
@Tag(name = "foo", description = "Some description")
public class FooResource {

  @GET
  @Path("/get-foo")
  @Produces(MediaType.TEXT_PLAIN)
  @Operation(summary = "Gets the foo")
  @APIResponses({ @APIResponse(responseCode = "200", description = "The foo") })
  public Response getFoo() {
    return Response.ok().build();
  }

  @GET
  @Path("/get-another-foo")
  @Produces(MediaType.TEXT_PLAIN)
  @Operation(summary = "Gets another foo")
  @APIResponses({ @APIResponse(responseCode = "200", description = "The foo") })
  @Tag(name = "foo", description = "Some other description")
  public Response getAnotherFoo() {
    return Response.ok().build();
  }
}

@Path("/bar")
@Tag(name = "foo", description = "Some totally different description")
public class BarResource {

  @GET
  @Path("/get-bar")
  @Produces(MediaType.TEXT_PLAIN)
  @Operation(summary = "Gets the bar")
  @APIResponses({ @APIResponse(responseCode = "200", description = "The bar") })
  public Response getBar() {
    return Response.ok().build();
  }
}

Note that the tag is always foo, but the description is sometimes different.

This is what I get:

{
  "openapi" : "3.0.3",
  "tags" : [ {
    "name" : "foo",
    "description" : "Some other description"
  } ],
  "paths" : {
    "/api/bar/get-bar" : {
      "get" : {
        "tags" : [ "foo" ],
        "summary" : "Gets the bar",
        "responses" : {
          "200" : {
            "description" : "The bar"
          }
        }
      }
    },
    "/api/foo/get-another-foo" : {
      "get" : {
        "tags" : [ "foo" ],
        "summary" : "Gets another foo",
        "responses" : {
          "200" : {
            "description" : "The foo"
          }
        }
      }
    },
    "/api/foo/get-foo" : {
      "get" : {
        "tags" : [ "foo" ],
        "summary" : "Gets the foo",
        "responses" : {
          "200" : {
            "description" : "The foo"
          }
        }
      }
    }
...
}

So the overridden description is ignored, and the global tag description for foo is kind of random...

Is it at all possible to override tag description in other resources or other endpoints?

[MikeEdgar]

Tag name and description are unique, and only declared in the top-level tags array of the OpenAPI doc. The operations themselves simply reference the tag(s) by name that apply to the operation. The @Tag annotation tries to make it more convenient by allowing you to declare the description and docs directly on the operations, but ultimately they are placed in the top-level array. If duplicate tag names are encountered, the description that is chosen is undefined.

[cristalp]

Ok, thanks for the clarification!