MyGit

Sayi/swagger-dubbo

Fork: 188 Star: 331 (更新于 2024-12-09 16:15:46)

license: Apache-2.0

Language: Java .

:page_with_curl: Dubbo的Swagger服务文档

最后发布版本: 3.0.0-beta ( 2024-01-31 19:28:00)

GitHub网址

Dubbo的Swagger服务文档

swagger-dubbo

Build Status jdk11+ dubbo3.2.0+

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请求参数为必填。

最近版本更新:(数据更新于 2024-09-03 01:41:41)

2024-01-31 19:28:00 3.0.0-beta

2018-06-07 01:01:29 2.0.1.RELEASE

主题(topics):

dubbo, http, swagger

Sayi/swagger-dubbo同语言 Java最近更新仓库

2024-12-20 19:54:15 mybatis-flex/mybatis-flex

2024-12-19 21:53:46 spring-projects/spring-boot

2024-12-19 21:25:16 Stirling-Tools/Stirling-PDF

2024-12-19 16:28:14 Tornaco/Thanox

2024-12-19 10:42:01 alibaba/nacos

2024-12-18 20:58:34 dromara/forest