类与方法含@Path注解时Swagger生成重复API记录的解决咨询

问题根因 #

swagger-maven-plugin-jakarta会扫描所有带有JAX-RS注解的类，你的接口类标注了@Path("/v1.0/private/communications")，实现类又额外标注了@Path("/")，插件同时解析接口和实现类后，分别组合出两条路径：

• 接口类+方法：/v1.0/private/communications/{id}
• 实现类+方法：/{id}

可行解决方案 #

• 移除实现类的@Path注解
  实现类会继承接口的@Path配置，不需要自己再标注@Path("/")，直接删掉这个注解，插件就只会解析接口类的路径配置，生成唯一的完整路径。

• 配置插件仅扫描接口类
  在pom.xml的插件配置里，指定扫描范围为接口所在包，或者排除实现类的包：

  <plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin-jakarta</artifactId>
    <version>2.2.38</version>
    <executions>
      <execution>
        <goals>
          <goal>resolve</goal>
        </goals>
        <configuration>
          <!-- 只扫描接口包 -->
          <scanBasePackages>
            <scanBasePackage>com.yourpackage.api</scanBasePackage>
          </scanBasePackages>
          <!-- 或者排除实现类包 -->
          <excludes>
            <exclude>com.yourpackage.impl/**</exclude>
          </excludes>
        </configuration>
      </execution>
    </executions>
  </plugin>
  

• 用@Hidden注解忽略实现类
  在实现类上添加@Hidden（io.swagger.v3.oas.annotations.Hidden）注解，插件会跳过该类的解析，只保留接口类生成的路径：

  @Hidden
  @Path("/")
  public class YourCommunicationImpl implements CommunicationApi {
      // 实现代码
  }
  

内容的提问来源于stack exchange，提问作者user31643023