📃 Dubbo的Swagger服务文档
Java
Clone or download
Latest commit 5675942 Aug 14, 2018
Permalink
Failed to load latest commit information.
swagger-dubbo-example 2.0.1.RELEASE Jun 6, 2018
swagger-dubbo 2.0.1.RELEASE Jun 6, 2018
.gitattributes gitattr Sep 4, 2017
.gitignore cache Sep 4, 2017
.travis.yml travis Sep 4, 2017
LICENSE apache license Sep 4, 2017
README.md Update README.md Aug 14, 2018
pom.xml 2.0.1.RELEASE Jun 6, 2018

README.md

swagger-dubbo

Build Status jdk1.6+ dubbo2.6.0+

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+ 有,示例文档 有,示例文档

更新日志参见Release Page

TO DO:接下来想基于swagger-dubbo建立一个微服务文档中心,将团队内所有微服务文档整合到一起,支持文档搜索,如果你有想法,欢迎联系我。

Maven

<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>swagger-dubbo</artifactId>
  <version>2.0.1</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容器,浏览器访问 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,加载配置文件。

<context:property-placeholder location="classpath*: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

跨域支持

  <!-- 跨域支持,Spring4.3.10+,低版本请设置拦截器开启跨域 -->
  <mvc:cors>
    <mvc:mapping path="/swagger-dubbo/**" allowed-origins="*" />
  </mvc:cors>

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

文章:探讨Dubbo与Swagger的集成