支持proto3

安装 protoc-gen-doc

简单遵循安装要求即可：

https://github.com/estan/protoc-gen-doc#installation

安装完成之后的protoc是2.5.0版本，无法处理proto3的文件。因此我们需要升级替换protoc为v3.0.0版本。

升级protoc

使用预编译版本

  1. 下载

    请先在 protobuf 的 发布页面 中找到对应版本的 download ，然后下载对应版本的 protoc, 如 v3.0.0的 linux 64位版本：

  2. 清理

    如果之前有安装过 protoc 的老版本，如2.5.0版本，则需要在安装前删除旧有版本的protoc和include文件，操作如下：

    1.  $ protoc --version
    2.  libprotoc 2.5.0
    3.  # 上面老版本是 2.5.0，需要删除
    4.  which protoc
    5.  /usr/bin/protoc
    6.  # 删除 protoc
    7.  sudo rm /usr/bin/protoc
    8.  # 删除默认的include文件
    9.  sudo rm -rf /usr/include/google/protobuf/

  3. 安装

    解压缩得到的zip文件，然后执行下面的操作，复制protoc和include文件：

    1.  mkdir temp
    2.  mv protoc-3.0.0-linux-x86_64.zip temp
    3.  cd temp
    4.  unzip protoc-3.0.0-linux-x86_64.zip

    输出如下(直接解压缩到当前目录，所以解压前最好准备一个临时目录，如上面shell命令中的temp目录):

    1.  Archive:  protoc-3.0.0-linux-x86_64.zip
    2.  creating: include/
    3.  creating: include/google/
    4.  creating: include/google/protobuf/
    5.  inflating: include/google/protobuf/struct.proto
    6.  inflating: include/google/protobuf/type.proto
    7.  inflating: include/google/protobuf/descriptor.proto
    8.  inflating: include/google/protobuf/api.proto
    9.  inflating: include/google/protobuf/empty.proto
    10.  creating: include/google/protobuf/compiler/
    11.  inflating: include/google/protobuf/compiler/plugin.proto
    12.  inflating: include/google/protobuf/any.proto
    13.  inflating: include/google/protobuf/field_mask.proto
    14.  inflating: include/google/protobuf/wrappers.proto
    15.  inflating: include/google/protobuf/timestamp.proto
    16.  inflating: include/google/protobuf/duration.proto
    17.  inflating: include/google/protobuf/source_context.proto
    18.  creating: bin/
    19.  inflating: bin/protoc
    20.  inflating: readme.txt

    开始复制文件并修改文件权限为755：

    1.  # 复制protoc文件
    2.  sudo cp bin/protoc /usr/bin/
    3.  sudo chmod 755 /usr/bin/protoc
    4.  # 复制include文件
    5.  sudo cp -r include/google/protobuf/ /usr/include/google/
    6.  sudo chmod -R 755 /usr/include/google/protobuf

生成文档

参考 protoc-gen-doc 的使用说明：

https://github.com/estan/protoc-gen-doc#invoking-the-plugin

注意：存放生成文件的目录必须预先建立，否则会报错。

  1. // 我们的proto文件在这里
  2. cd contract/src/main/proto
  3. // 准备生成HTML文件，并放置在target/contract-doc目录下
  4. mkdir ../../../target/contract-doc
  5. protoc --doc_out=html,index.html:../../../target/contract-doc userService.proto

解决 import 问题

执行 protoc 时，如果 userService.proto 还 import 了 google/protobuf 之外的其他的 .proto 文件，则会因为无法找到需要的 import 文件而报错。

有三种方式解决：

  1. 直接将要import的proto文件复制到当前目录，保证路径正确

  2. 将需要import的proto文件复制到 /usr/include/ 目录

    1.  sudo cp -r dolphin/ /usr/include/
    2.  sudo chmod -R 755 /usr/include/dolphin/

  3. 使用 --proto_path=PATH 在 protoc 的命令行参数中添加import的路径，而且这个选项可以使用多次

总结

现在至少可以用了，可以得到生成的HTML文件，虽然还有很多不足，后续再更新。

后续工作

后面就可以考虑：

  1. 在jenkins上建立上述环境
  2. 然后添加job来为各个项目的contract文件生成HTML文档
  3. 再将生成的文档统一发布到nginx之类的服务器下

这样就可以实现一个简单的文档中心，用于各个服务API文档的统一维护和发布。