公告：
? ? ?
随着dubbo的蓬勃发展，个人对这个项目又有了一点新的期待和想法(功能和架构上)，目前开通了群聊频道，欢迎加入讨论：加入Gitter群
swagger-dubbo起一个解析Swagger和收集文档的作用
dubbo-swagger-doc是一个web应用，从注册中心获取所有文档，是一个dubbo接口的swagger文档
dubbo-static-doc是一个dubbo接口的静态文档
dubbo-apidoc是一个dubbo接口的javaAPI文档
swagger-dubbo
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
dubbo2.5.3
否
有
无
2.0.1
dubbo2.6.0+
是
Maven
com.deepoove
swagger-dubbo
2.0.1
两步集成
一. 使用注解 @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。
集成已经完毕，启动web容器，浏览器访问 http://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-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默认无需任何配置，但是也提供了一些可选项。
新增文件swagger-dubbo.properties，加载配置文件。
配置项说明：
#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
跨域支持
SpringBoot 集成 Swagger-dubbo
SpringBoot对配置做了简化，集成swagger-dubbo只需要做第一步就可以了：使用注解 @EnableDubboSwagger开启dubbo的swagger文档。参见spring-boot示例
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请求参数为必填。