2024-02-28

Protobuf 文档生成器插件

阅读 |共232字

预计阅读约: 2 分钟

这是 Google Protocol Buffers 文档生成器插件 (protoc)。 该插件可以根据文件中的注释生成 HTML、JSON、DocBook 和 Markdown 文档。

一、前言

毫无疑问, 目前后台开发接口协议应用最广泛的除了 HTTP 之外就是 gRPC 了, HTTP 接口有成熟的swagger工具可以生成界面美观和使用友好的文档，那么对于gRPC呢？

所以通过 .proto 文件能否生成更易阅读的 HTML 接口文档？

二、安装

go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest

三、使用

user.proto 文件

1. 以user.proto为例, 如下内容:

   syntax = "proto3";
   
   option go_package = "./pb";
   
   package user;
   
   // ------------------------------------
   // Messages
   // ------------------------------------
   
   //--------------------------------用户--------------------------------
   
   message SysUser {
       int64  id        = 1; // ID
       string username  = 2; // 用户名
       string password  = 3; // 密码
       int64  create_at = 4; // 创建时间
       int64  update_at = 5; // 修改时间
       int64  delete_at = 6; // 删除时间
   }
   
   message SysUserFilter {
       optional int64  id        = 1; // ID
       optional string username  = 2; // 用户名
       optional string password  = 3; // 密码
       optional int64  create_at = 4; // 创建时间
       optional int64  update_at = 5; // 修改时间
       optional int64  delete_at = 6; // 删除时间
   }
   
   message SelectSysUserListReq {
       int64                  page      = 1; // 页码
       int64                  page_size = 2; // 每页数量
       optional SysUserFilter filter    = 3; // SysUserFilter
   }
   
   message SelectSysUserListResp {
       int64            count      = 1; // 总数
       int64            page_count = 2; // 页码总数
       repeated SysUser results    = 3; // sys_user
   }
   
   // ------------------------------------
   // Rpc Func
   // ------------------------------------
   
   service User {
   
       //-----------------------用户-----------------------
   
       // 用户 列表
       rpc SelectSysUserList(SelectSysUserListReq) returns (SelectSysUserListResp);
   }
   

1. 生成 markdown 文档

1. 命令:

   protoc --doc_out=. --doc_opt=markdown,index.md pb/*.proto
   

2. 效果:

2. 生成 html 文档

1. 命令:

   protoc --doc_out=. --doc_opt=html,index.html pb/*.proto
   

2. 效果:

四、自定义模板

如果想使用自己的模板, 只需使用模板文件的路径而不是类型。

protoc --doc_out=./doc --doc_opt=/path/to/template.tmpl,index.txt proto/*.proto

/path/to/template.tmpl 模板文件路径为自定义路径

官方文档: https://github.com/pseudomuto/protoc-gen-doc/wiki/Custom-Templates