如何生成dubbo rpc接口文档

在国内dubbo成为不少互联网公司高并发分布式场景下rpc框架的首选，dubbo从开源至今经历过蛮多的过程，从开源到中间的中止维护，通过三年的沉寂，2017年9月，阿里巴巴宣布重启dubbo项目。到2018年2月，阿里将dubbo捐献给Apache基金会，随后dubbo通过孵化后顺利成为apache的顶级项目。

固然本文的重点不是介绍dubbo的使用，而是介绍如何利用smart-doc工具来生成dubbo的rpc内部接口文档。smart-doc由于其基于注释和java接口定义自动推导的理念，开源以来受到国内不少开发者的喜好。在开源之初，smart-doc仅仅支持restful api文档的生成，可是在发展的过程当中，不断有开发者询问smart-doc可否支持dubbo rpc接口文档的生成。通过不断努力，在smart-doc 1.8.7版本中咱们增长了dubbo rpc接口的支持，下面来看看真正的操做。

1、集成smart-doc

smart-doc本着使用简单的原则开发了maven插件和gradle，经过插件来下降smart-doc的集成难度和去除依赖侵入性。您能够根据本身使用的依赖构建管理工具来选择相关的插件，下面以使用smart-doc-maven-plugin插件集成smart-doc生成dubbo为例。固然集成smart-doc来生成dubbo rpc接口文档你有两种可选方式：

• 使用smart-doc扫描dubbo api模块
• 使用smart-doc扫描dubbo provider模块

下面来看下集成方式。

1.1 添加插件

在你的dubbo api或者或者是dubbo provider模块中添加smart-doc-maven-plugin。固然你只须要选中一种方式便可

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在本身的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，若是一些框架依赖库加载不到致使报错，这时请使用excludes排除掉-->
        <excludes>
            <!--格式为：groupId:artifactId;参考以下-->
            <!--1.0.7版本开始你还能够用正则匹配排除,如：poi.* -->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--自1.0.8版本开始，插件提供includes支持-->
        <!--smart-doc能自动分析依赖树加载全部依赖源码，原则上会影响文档构建效率，所以你可使用includes来让插件加载你配置的组件-->
        <includes>
            <!--格式为：groupId:artifactId;参考以下-->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--若是不须要在执行编译时启动smart-doc，则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

添加smart-doc所需配置文件

在你的dubbo api或者或者是dubbo provider模块reources中添加smart-doc.json配置文件

{
  "isStrict": false, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中，通常推荐为true
  "outPath": "D://md2", //指定文档的输出路径
  "projectName": "smart-doc",//配置本身的项目名称
  "rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成
      "artifactId":"SpringBoot2-Dubbo-Api",
      "groupId":"com.demo",
      "version":"1.0.0"
  }],
  "rpcConsumerConfig":"src/main/resources/consumer-example.conf"//文档中添加dubbo consumer集成配置，用于方便集成方能够快速集成
}

关于smart-doc若是你生成文档须要更详细的配置请常看官方项目wiki文档
官方wiki文档

rpcConsumerConfig：

若是下你想让dubbo consumer集成更加快速，你能够将集成配置示例consumer-example.conf中，Smart-doc会将该示例直接输出到文档中。

dubbo:
  registry:
    protocol: zookeeper
    address:  ${zookeeper.adrress}
    id: my-registry
  scan:
    base-packages: com.iflytek.demo.dubbo
  application:
    name: dubbo-consumer

dubbo接口扫描

上面提到了smart-doc支持单独去扫描dubbo api或者dubbo provider。在扫描原理是主要经过识别@dubbo注释tag(idea能够支持添加自定义注释tag提示能够参考smart-doc wiki文档介绍)或dubbo的 @service注解。

扫描dubbo api

dubbo api一般都是很简洁的dubbo接口定义，若是你须要让smart-doc扫描到dubbo接口，那么须要加上@dubbo注释tag。示例以下：

/**
 * 用户操做
 *
 * @author yu 2019/4/22.
 * @author zhangsan 2019/4/22.
 * @version 1.0.0
 * @dubbo
 */
public interface UserService {

    /**
     * 查询全部用户
     *
     * @return
     */
    List<User> listOfUser();

    /**
     * 根据用户id查询
     *
     * @param userId
     * @return
     */
    User getById(String userId);
}

扫描dubbo provider

若是想经过dubbo provider生成rpc接口文档的状况，你不须要加任何的其余注释tag，smart-doc自动扫描@service注解完成。

/**
 * @author yu 2019/4/22.
 */
@Service
public class UserServiceImpl implements UserService {

    private static Map<String,User> userMap = new HashMap<>();

    static {
        userMap.put("1",new User()
                .setUid(UUIDUtil.getUuid32())
                .setName("zhangsan")
                .setAddress("四川成都")
        );
    }
    
    /**
     * 获取用户
     * @param userId
     * @return
     */
    @Override
    public User getById(String userId) {
        return userMap.get(userId);
    }

    /**
     * 获取用户
     * @return
     */
    @Override
    public List<User> listOfUser() {
        return userMap.values().stream().collect(Collectors.toList());
    }
}

生成操做

直接经过maven命令运行插件的文档生成命令或者在idea中直接单击插件的可视化命令便可。

dubbo-api文档生成效果图

Add dependency

<dependency>
    <groupId>com.demo</groupId>
    <artifactId>SpringBoot2-Dubbo-Api</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>com.demo</groupId>
    <artifactId>SpringBoot2-Dubbo-Api</artifactId>
    <version>1.0.0</version>
</dependency>

用户操做

URI: dubbo://localhost:20880/com.iflytek.demo.dubbo.api.interfaces.UserService

Service: com.iflytek.demo.dubbo.api.interfaces.UserService

Protocol: dubbo

Author: yu 2019/4/22., zhangsan 2019/4/22.

Version: 1.0.0

查询全部用户

Definition： List<User> listOfUser()

Description: 查询全部用户

Response-fields:

Field	Type	Description	Since
uid	String	用户id	-
name	String	用户名称	-
address	String	地址	-

根据用户id查询

Definition： User getById(String userId)

Description: 根据用户id查询

Invoke-parameters:

Parameter	Type	Description	Required	Since
userId	String	用户id	true	-

Response-fields:

Field	Type	Description	Since
uid	String	用户id	-
name	String	用户名称	-
address	String	地址	-

使用总结

smart-doc对于dubbo rpc文档生成的支持比较晚，固然目前市面也没有比其余比较好的工具以及模板参考。dubbo rpc文档的这块还须要更多的用户提出issue和改进意见。固然若是你认同和喜欢smart-doc请前往项目给咱们一些支持点点star。

码云地址

Github地址