SpringBoot swagger-dubbo 整合

加入 maven 依赖，这里使用的 springfox.version 版本是 2.7.0 (2.9.2 有问题)，swagger.version 版本是 1.5.20（需要手动引入 swagger 相关依赖，避免引入 1.5.13 造成冲突），
swagger-dubbo 版本是 2.0.1


    <springfox.version>2.7.0</springfox.version>
    <swagger.version>1.5.20</swagger.version>
    <spring.dubbo.version>2.0.1</spring.dubbo.version>
<!-- Swagger Core -->
      <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-core</artifactId>
        <version>${swagger.version}</version>
      </dependency>

      <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>${swagger.version}</version>
      </dependency>

      <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>${swagger.version}</version>
      </dependency>
<!-- swagger ui -->
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${springfox.version}</version>
        <exclusions>
          <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-beans</artifactId>
          </exclusion>
        </exclusions>
      </dependency>
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${springfox.version}</version>
      </dependency>

      <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>swagger-ui</artifactId>
        <version>3.17.6</version>
      </dependency>

      <dependency>
        <groupId>com.deepoove</groupId>
        <artifactId>swagger-dubbo</artifactId>
        <version>${spring.dubbo.version}</version>
      </dependency>

在 SwaggerDubboConfiguration 上加入注解 @EnableDubboSwagger
通过 PropertySource 配合 Configuration 一起使用将 swagger-dubbo.properties 属性变量注入到 Spring's Environment

JavaConfig 配置如下：

/**
 * @Author: zyn
 * @Description: PropertySource 配合 Configuration一起使用将属性注入到 Spring's Environment
 *                这里不重写 addResourceHandler 方法的原因是，在 SwaggerConfiguration 中已经
 *                将 classpath:/META-INF/resources/ 添加到了静态资源目录，当访问 swagger-dubbo-ui.html 时
 *                默认去 classpath:/META-INF/resources/ 目录下查找对应的 html
 * @Date: Created in 2018-10-31 11:11
 * @Modified By:
 */
@Configuration
@EnableDubboSwagger
@PropertySource(value = "classpath:env/swagger-dubbo.properties", ignoreResourceNotFound = true, encoding = "UTF-8")
public class SwaggerDubboConfiguration extends WebMvcConfigurerAdapter {

//  @Override
//  public void addResourceHandlers(ResourceHandlerRegistry registry) {
//    registry.addResourceHandler("swagger-dubbo-ui.html")
//        .addResourceLocations("classpath:/META-INF/resources/");
//  }
  
}

swagger-dubbo.properties 配置如下

#http请求地址，默认为http://ip:port/h/com.XXX.XxService/method
swagger.dubbo.http=dubbo

#dubbo 服务版本号
swagger.dubbo.application.version = v1.0.0
#dubbo服务groupId
swagger.dubbo.application.groupId = com.xxx
#dubbo服务artifactId
swagger.dubbo.application.artifactId = back-trade-dubbo-provider

#rpc zk调用 or 本地调用
swagger.dubbo.cluster = rpc

#是否启用swagger-dubbo，默认为true,如果是生产环境就设置为false
swagger.dubbo.enable = true

在 resources 下新建如下目录，并加入静态资源

image.png

swagger-ui.html 从如下目录拷贝

image.png
swagger-dubbo-ui.html 从 https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html 拷贝，并修改资源引入路径（修改为 webjar 引入）
修改 SwaggerConfiguration 配置文件，继承 WebMvcConfigurerAdapter，添加资源处理器和静态资源位置

@Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/webjars/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/");

    registry.addResourceHandler("swagger-ui.html")
        .addResourceLocations("classpath:/META-INF/resources/");
  }

访问 http://localhost:9091/swagger-dubbo-ui.html，结果如下图

image.png

参考文章

总结：

集成 swagger-dubbo 的时候发现 @ApiModel 标记的实体在 swagger-dubbo-ui.html 页面上不显示的问题，debug 跟踪源码发现，只有接口方法返回单个对象的时候，才能扫描到，例如 List<TradeDto> test(); 不显示，而TradeDto test(); 显示
由于 dubbo 服务中设置了分组，导致不能进行接口测试，所有设置都不进行分组的话，则可以进行接口测试（同事大神告诉我的，暂时还没有进行测试）
此 swagger-dubbo 查询接口，实体信息的接口地址是 /swagger-dubbo/api-docs，而不是 /swagger-dubbo/swagger.json

image.png

SpringBoot swagger-dubbo 整合

推荐阅读更多精彩内容