随着dubbo的蓬勃发展,个人对这个项目又有了一点新的期待和想法(功能和架构上),目前开通了群聊频道,欢迎加入讨论:加入Gitter群
- swagger-dubbo起一个解析Swagger和收集文档的作用
- dubbo-swagger-doc是一个web应用,从注册中心获取所有文档,是一个dubbo接口的swagger文档
- dubbo-static-doc是一个dubbo接口的静态文档
- dubbo-apidoc是一个dubbo接口的javaAPI文档
Dubbo |ˈdʌbəʊ| 是阿里巴巴提供的分布式框架,提供高性能和透明化的RPC远程服务调用方案,以及SOA服务治理方案。
Swagger围绕着OpenAPI规范,提供了一套设计、构建、文档化rest api的开源工具。
swagger-dubbo的核心价值是swagger式的文档化+rest风格的HTTP模拟测试。
- 通过swagger阅读接口文档
- 开发人员可以用它来自测服务接口,也可以用它来模拟别人的服务接口返回值
- 测试可以用它来验证接口的正确性,基于HTTP进行接口测试
swagger-dubbo从某些方面提高了内部开发测试的效率,注意的是,rest服务不适合对外(前端)提供,务必在服务端或者测试内部使用
swagger-dubbo版本 | 支持dubbo版本号 | 支持dubbo注解 | SpringMVC demo | SpringBoot demo |
---|---|---|---|---|
1.1.0 移步老版本文档分支 | dubbo2.5.3 | 否 | ✅ 有 | 无 |
2.0.1 | dubbo2.6.0+ | ✅ 是 | ✅ 有,示例文档 | ✅ 有,示例文档 |
2.0.2-SHAPSHOT | alibaba dubbo2.6.0+ apache dubbo2.7.6+ |
✅ 是 | ✅ 有,示例文档 | ✅ 有,示例文档 改进自动装配不需再写包扫描,改进yml提示 |
更新日志参见Release Page
<dependency>
<groupId>com.deepoove</groupId>
<artifactId>swagger-dubbo</artifactId>
<version>2.0.2-SNAPSHOT</version>
</dependency>
一. 使用注解 @EnableDubboSwagger
开启dubbo的swagger文档。
package com.deepoove.swagger.dubbo.example;
import org.springframework.context.annotation.Configuration;
import com.deepoove.swagger.dubbo.annotations.EnableDubboSwagger;
@Configuration
@EnableDubboSwagger
public class SwaggerDubboConfig {
}
二. 在spring的*-servlet.xml配置中,开启属性占位符的配置,开启Configuration注解,声明SwaggerDubboConfig。
<context:annotation-config />
<bean class="com.deepoove.swagger.dubbo.example.SwaggerDubboConfig" />
<context:property-placeholder />
集成已经完毕,启动web容器,浏览器访问 https://ip:port/context/swagger-dubbo/api-docs
查看文档。
{
"swagger": "2.0",
"info": {
"version": "1.0",
"title": "dubbo-example-app",
"contact": {
"name": "Sayi"
}
},
"basePath": "/dubbo-provider",
"paths": {
"/h/com.deepoove.swagger.dubbo.example.api.service.UserService/get": {
"get": {
"tags": [
"UserService"
],
"summary": "获取用户",
"description": "User get(java.lang.String)通过id取用户信息",
"operationId": "get",
"parameters": [
{
"name": "id",
"in": "query",
"description": "用户id",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "",
"schema": {
"$ref": "#/definitions/User"
}
}
}
}
}
},
"definitions": {
"User": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"description": "用户姓名"
},
"site": {
"type": "string"
}
}
}
}
}
可以在任何能托管页面的容器内集成swagger-ui,配置swagger-dubbo提供的https://ip:port/context/swagger-dubbo/api-docs
,可能需要跨域支持,详情参见官方文档 swagger-ui
@JKTerrific 在swagger-ui基础上开发了swagger-dubbo-ui, 解决了页面上的一些展示问题:
- 参数为model时,输入框变更为输入域,并且支持JSON可视化
- Model字段为date、byte时,支持展示具体类型,而不是string
swagger-dubbo默认无需任何配置,但是也提供了一些可选项。
新增文件swagger-dubbo.properties,加载配置文件。
<context:property-placeholder location="classpath*:swagger-dubbo.properties" />
配置项说明:
#http请求地址,默认为https://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
<!-- 跨域支持,Spring4.3.10+,低版本请设置拦截器开启跨域 -->
<mvc:cors>
<mvc:mapping path="/swagger-dubbo/**" allowed-origins="*" />
</mvc:cors>
SpringBoot对配置做了简化,集成swagger-dubbo只需要做第一步就可以了:使用注解 @EnableDubboSwagger
开启dubbo的swagger文档。参见spring-boot示例
-
对于服务接口方法重载,为了在http请求中唯一确认一个方法,需要使用注解
@ApiOperation(nickname = "byArea")
,通过nickname标记唯一路径(如果不填写,将只显示一个方法)。此时,rest的请求地址为:https://ip:port/h/com.XXX.XxService/method/byArea
Stackoverflow:重载的方法能够映射到同一URL地址吗 -
Object对象作为http请求参数为json string格式。 Stackoverflow:POST的方法能够接收多个参数吗?
-
swagger注解既可以写在接口上,也可以写在实现类上。
-
原生类型作为http请求参数为必填。