swagger-dubbo

Dubbo |ˈdʌbəʊ| 是阿里巴巴提供的分布式框架，Swagger 围绕着 OpenAPI 规范，提供了一套设计、构建、文档化 rest api 的开源工具。

• 通过 swagger 阅读接口文档
• 开发人员可以用它来自测服务接口，也可以用它来模拟别人的服务接口返回值
• 测试可以用它来验证接口的正确性，基于 HTTP 进行接口测试

前提

• Apache Dubbo 3.2+
• JDK 11+

Maven

<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>swagger-dubbo</artifactId>
  <version>3.0.0-beta</version>
</dependency>

SpringBoot

@EnableDubboSwagger开启 dubbo 的 swagger 文档。

@EnableDubboSwagger
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

参见spring-boot 示例

swagger-ui 查看文档

可以在任何能托管页面的容器内集成 swagger-ui，配置 swagger-dubbo 提供的http://ip:port/context/swagger-dubbo/api-docs，可能需要跨域支持，详情参见官方文档 swagger-ui

@JKTerrific 在 swagger-ui 基础上开发了swagger-dubbo-ui, 解决了页面上的一些展示问题：

• 参数为 model 时，输入框变更为输入域，并且支持 JSON 可视化
• Model 字段为 date、byte 时，支持展示具体类型，而不是 string

配置

swagger-dubbo 默认无需任何配置，但是也提供了一些可选项。

配置项说明：

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

#dubbo 服务版本号
swagger.dubbo.application.version = 1.0
#dubbo 服务 groupId
swagger.dubbo.application.groupId = com.deepoove
#dubbo 服务 artifactId
swagger.dubbo.application.artifactId = dubbo.api

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

#是否启用 swagger-dubbo，默认为 true
swagger.dubbo.enable = true

swagger-dubbo 集成注意事项

• 对于服务接口方法重载，为了在 http 请求中唯一确认一个方法，需要使用注解@ApiOperation(nickname = "byArea"),通过 nickname 标记唯一路径(如果不填写，将只显示一个方法)。此时，rest 的请求地址为：http://ip:port/h/com.XXX.XxService/method/byArea Stackoverflow:重载的方法能够映射到同一 URL 地址吗

• Object 对象作为 http 请求参数为 json string 格式。 Stackoverflow:POST 的方法能够接收多个参数吗？

• swagger 注解既可以写在接口上，也可以写在实现类上。

• 原生类型作为 http 请求参数为必填。