https://github.com/sayi/swagger-dubbo
:page_with_curl: Dubbo的Swagger服务文档
https://github.com/sayi/swagger-dubbo
dubbo http swagger
Last synced: 7 months ago
JSON representation
:page_with_curl: Dubbo的Swagger服务文档
- Host: GitHub
- URL: https://github.com/sayi/swagger-dubbo
- Owner: Sayi
- License: apache-2.0
- Created: 2017-09-04T09:10:51.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-09-13T20:33:35.000Z (about 1 year ago)
- Last Synced: 2025-03-31T14:09:11.436Z (7 months ago)
- Topics: dubbo, http, swagger
- Language: Java
- Homepage:
- Size: 1.84 MB
- Stars: 332
- Watchers: 24
- Forks: 188
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Dubbo的Swagger服务文档
## swagger-dubbo
[](https://travis-ci.org/Sayi/swagger-dubbo)  
Dubbo |ˈdʌbəʊ| 是阿里巴巴提供的分布式框架，Swagger围绕着OpenAPI规范，提供了一套设计、构建、文档化rest api的开源工具。
* 通过swagger阅读接口文档
* 开发人员可以用它来自测服务接口，也可以用它来模拟别人的服务接口返回值
* 测试可以用它来验证接口的正确性，基于HTTP进行接口测试
## 前提
- Apache Dubbo 3.2+
- JDK 11+
## Maven
```xml
com.deepoove
swagger-dubbo
3.0.0-beta
```
## SpringBoot
`@EnableDubboSwagger`开启dubbo的swagger文档。
```java
@EnableDubboSwagger
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
参见[spring-boot示例](swagger-dubbo-example/dubbo-provider-springboot)
## swagger-ui查看文档
可以在任何能托管页面的容器内集成swagger-ui，配置swagger-dubbo提供的`http://ip:port/context/swagger-dubbo/api-docs`，可能需要跨域支持，详情参见官方文档 [swagger-ui](https://github.com/swagger-api/swagger-ui)
@JKTerrific 在swagger-ui基础上开发了[**swagger-dubbo-ui**](https://github.com/JKTerrific/swagger-dubbo-ui), 解决了页面上的一些展示问题：
* 参数为model时，输入框变更为输入域，并且支持JSON可视化
* Model字段为date、byte时，支持展示具体类型，而不是string
## 配置
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
```
## swagger-dubbo集成注意事项
* 对于服务接口方法重载，为了在http请求中唯一确认一个方法，需要使用注解`@ApiOperation(nickname = "byArea")`,通过nickname标记唯一路径(如果不填写，将只显示一个方法)。此时，rest的请求地址为：`http://ip:port/h/com.XXX.XxService/method/byArea`
[Stackoverflow:重载的方法能够映射到同一URL地址吗](http://stackoverflow.com/questions/17196766/can-resteasy-choose-method-based-on-query-params)
* Object对象作为http请求参数为json string格式。
[Stackoverflow:POST的方法能够接收多个参数吗？](http://stackoverflow.com/questions/5553218/jax-rs-post-multiple-objects)
* swagger注解既可以写在接口上，也可以写在实现类上。
* 原生类型作为http请求参数为必填。