swagger-dubbo

Project Url: Sayi/swagger-dubbo
Introduction: :page_with_curl: Dubbo 的 Swagger 服务文档
More: Author   ReportBugs   
Tags:

随着 dubbo 的蓬勃发展,个人对这个项目又有了一点新的期待和想法(功能和架构上),目前开通了群聊频道,欢迎加入讨论:加入 Gitter 群

image

  • swagger-dubbo 起一个解析 Swagger 和收集文档的作用
  • dubbo-swagger-doc 是一个 web 应用,从注册中心获取所有文档,是一个 dubbo 接口的 swagger 文档
  • dubbo-static-doc 是一个 dubbo 接口的静态文档
  • dubbo-apidoc 是一个 dubbo 接口的 javaAPI 文档

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 :white_check_mark: 有
2.0.1 dubbo2.6.0+ :white_check_mark: 是 :white_check_mark: 有,示例文档 :white_check_mark: 有,示例文档

更新日志参见Release Page

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 请求参数为必填。
Support Me
Apps
About Me
Google+: Trinea trinea
GitHub: Trinea