Dropwizard已有REST API项目如何添加openapi.yaml配置Swagger UI

你现有已完成REST API开发的Dropwizard项目，按以下步骤操作即可实现需求：

1. 引入兼容依赖 #

首先在项目构建配置中引入dropwizard-swagger组件，注意版本必须和你当前使用的Dropwizard主版本保持兼容，Maven项目在pom.xml中添加如下依赖：

<dependency>
    <groupId>io.federecio</groupId>
    <artifactId>dropwizard-swagger</artifactId>
    <version>与当前Dropwizard版本匹配的发行版</version>
</dependency>

Gradle项目对应引入同坐标依赖即可。

2. openapi.yaml存放路径 #

如果你使用提前编写完成的静态openapi.yaml文件，直接将文件放入src/main/resources目录即可，项目编译打包后该文件会处于classpath根路径，可被框架直接识别加载。
如果你不需要静态预定义文件，框架可以自动扫描项目中的REST资源类、Swagger注解动态生成OpenAPI定义，无需手动维护全量yaml内容。

3. 必要配置步骤 #

• 第一步：在项目的Application启动类中注册Swagger Bundle
  重写initialize方法，在原有逻辑基础上添加Swagger组件注册逻辑，示例代码如下：

  @Override
  public void initialize(Bootstrap<你的项目自定义Configuration类> bootstrap) {
      // 保留你原有的bundle注册、对象映射配置等逻辑
      bootstrap.addBundle(new SwaggerBundle<你的项目自定义Configuration类>() {
          @Override
          protected SwaggerBundleConfiguration getSwaggerBundleConfiguration(你的项目自定义Configuration类 config) {
              return config.getSwaggerConfig();
          }
      });
  }
  

• 第二步：在项目自定义Configuration类中添加Swagger配置字段

  @Valid
  @NotNull
  private SwaggerBundleConfiguration swaggerConfig = new SwaggerBundleConfiguration();
  
  public SwaggerBundleConfiguration getSwaggerConfig() {
      return swaggerConfig;
  }
  

• 第三步：在项目启动配置文件（如application.yml、dev.yml等Dropwizard运行时加载的配置文件）中添加Swagger配置段，如果使用静态openapi.yaml，配置参考如下：

  swaggerConfig:
    resourcePackage: 项目中REST资源类所在的全包路径，例：com.yourorg.project.api.resource
    openApi:
      location: classpath:openapi.yaml # 指向resources目录下的静态yaml文件
    ui:
      enabled: true # 显式开启Swagger UI页面
  

  如果使用动态生成的OpenAPI定义，删除openApi.location配置项即可，框架会自动扫描指定包下的资源生成接口定义。

4. 生效验证 #

正常启动项目后，直接访问对应地址即可验证效果：

• 接口定义访问地址：http://{服务IP}:{服务端口}/openapi.yaml
• Swagger UI访问地址：http://{服务IP}:{服务端口}/swagger

常见排查点：如果访问Swagger UI报404，优先检查ui.enabled是否为true、resourcePackage路径是否和实际资源类存放路径一致、静态yaml的配置路径是否和实际存放位置匹配。

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