[BUG][JavaSpring] Not wanted automatic inserted tags if there're ones in OpenAPI definition

[pichlau]

Bug Report Checklist

• [x] Have you provided a full/minimal spec to reproduce the issue?
• [x] Have you validated the input using an OpenAPI validator (example)?
• [x] Have you tested with the latest master to confirm the issue still exists?
• [x] Have you searched for related issues/PRs?
• [x] What's the actual output vs expected output?
• [ ] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

From the openapi definition (see below) when I open it in the online editor https://editor.swagger.io/ I get the following swagger-ui page. Only the tags present in the definition appear.

When I use the JavaSpring generator with the same openapi definition, the generated java interface contains @Tag annotation on the generated interface deduced from endpoint path, with automatic generated description value.

And the swagger-ui page display it in addition to the one already present in the definition.

I don't want the generated tag because I define mine directly in the definition. I don't found an option (in the documentation nor in the api.mustashe) to avoid this generation.

openapi-generator version

v5.4.0

OpenAPI declaration file content or url

openapi: 3.0.3
info:
  title: API example
  version: "1.0.0"
  description: "OpenAPI definition to illustrate the issue xxx"
tags:
  - name: authentication
    description: "All API concerning authentification."
paths:
  /auth/login:
    get:
      tags:
        - authentication
      summary: API for login
      operationId: authLogin
      security: []
      parameters: []
      responses:
        '200':
          description: "OK"
          content:
            text/html:
              schema:
                type: string
        '401':
          description: "Unauthorized"
          content:
            text/html:
              schema:
                type: string

Generation Details

The genererated interface contains :

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen")
@Validated
@Tag(name = "auth", description = "the auth API")
public interface AuthApi {
[...]
    /**
     * GET /auth/login : API for login
     *
     */
    @Operation(
        operationId = "authLogin",
        summary = "API for login",
        tags = { "authentication" },
        [...]

Steps to reproduce

Clear

Related issues/PRs

Clear

Suggest a fix

[pichlau]

Can anyone help me, please ?

[borsch]

Hi @pichlau. I'll try to review this over weekend

[pichlau]

Thank you @borsch for your help.

[borsch]

@pichlau seems like you need simply enable useTags config option (it's disabled by default). You can check documentation https://openapi-generator.tech/docs/generators/spring

[pichlau]

When I use this option, the generated interface name start with the tag name AuthenticationApi instead of the endpoint name AuthApi., ok but that is not what I want. And the automatic annotation @Tag(name="Authentication", description)"the Authentication API" is still generated above the interface declaration, and it is this annotation that causes the wrong tag entry in swagger-ui.

The expected output should be :

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen")
@Validated
public interface AuthApi {

=> without any tag annotation on the interface if there are tags in the openapi definition

In the openapi yaml definition the tags are associated only with operations /auth/login, not with the root path of endpoints /auth, so I think we can't associate to the interface AuthApi the tag present in the definition.

Moreover, an operation can receive several tags. In the definition with the prefix auth, I can definine an operation auth/login with the tag authentication and another operation auth/status without any tag so that the generator should not affect the tag authentication neither to the common root auth nor to the AuthApi interface.

I feel like there should just be a new option disableTagAnnotation (default to false for backward compatibility) to not generate the @tag annotation on interfaces.

[jkoorts]

This is hell of frustrating. I have to release software to a client, and swagger ui shows this :

usages the usages API

Which was generated out if thin air. The text "the usages API" is generated by this tool.

My tag shows:

  tags:
    - Usage

The endpoint is /usages

In my swagger UI both tags shows up. Mine and this autogenerated one.

[jkoorts]

I've now forked this project, and just removed the @Tag stuff from the mustache.

I then add my own @Tag information in my controller. So now the Interface that had the @Tag is now tagless and swagger ui picks up my @Tag.

The mustache had this:

@Api(value = "{{{baseName}}}", description = {{#tagDescription}}"{{{.}}}"{{/tagDescription}}{{^tagDescription}}"the {{{baseName}}} API"{{/tagDescription}})

Why put "the API" as hard coded? What about I8n? What about people not wanting this? Then why {{baseName}}. Usually basename is lower case and that looks crap in swagger ui.

[anitha2010]

Am also stuck with same problem. @jkoorts how you removed the @tag stuff from the mustache.

[jkoorts]

Fork, then remove:

@Tag(name = "{{{baseName}}}", description = {{#tagDescription}}"{{{.}}}"{{/tagDescription}}{{^tagDescription}}"the {{{baseName}}} API"{{/tagDescription}})

from api.mustache

[jkoorts]

I solved my duplication by removing @Tag from my @RestController. Also try removing the tags section in spec.

Then finally to get the "the xxxx API" text removed you have to follow my suggestion in previous post.

[anitha2010]

Fork, then remove:

@tag(name = "{{{baseName}}}", description = {{#tagDescription}}"{{{.}}}"{{/tagDescription}}{{^tagDescription}}"the {{{baseName}}} API"{{/tagDescription}})

from api.mustache

@jkoorts Do you add any custom file to remove the code from api.mustache because i dont see any file"api.mustache" in my project

[jkoorts]

You need to fork this openapi-generator application from github. Change the code and compile your own binaries and use that.

On Fri, 2 Dec 2022, 11:50 anitha2010, @.***> wrote:

Fork, then remove:

@tag https://github.com/tag(name = "{{{baseName}}}", description = {{#tagDescription}}"{{{.}}}"{{/tagDescription}}{{^tagDescription}}"the {{{baseName}}} API"{{/tagDescription}})

from api.mustache

@jkoorts https://github.com/jkoorts Do you add any custom file to remove the code from api.mustache because i dont see any file"api.mustache" in my project

— Reply to this email directly, view it on GitHub https://github.com/OpenAPITools/openapi-generator/issues/11818#issuecomment-1335001729, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACPLRZJUQJER6BWLLCXYPUTWLHA7ZANCNFSM5QDOVLHA . You are receiving this because you were mentioned.Message ID: @.***>