Hertz框架中使用protoc-gen-openapi生成API文档的实践指南

背景介绍

在微服务架构中，API文档是前后端协作的重要桥梁。Hertz作为一款高性能的Go HTTP框架，支持通过protobuf定义服务接口，并提供了多种文档生成工具。本文将详细介绍如何在Hertz项目中使用protoc-gen-openapi插件生成OpenAPI规范文档。

准备工作

环境要求

• Hertz版本：v0.8.1或更高
• protoc编译器：libprotoc 25.3或更高
• protoc-gen-openapi插件：通过go install安装最新版本

依赖文件准备

使用protoc-gen-openapi需要准备以下依赖的proto文件：

1. google/protobuf下的descriptor.proto等基础定义文件
2. google/api下的annotations.proto和http.proto
3. openapiv3下的annotations.proto和OpenAPIv3.proto

这些文件需要放置在正确的目录结构中，以便protoc能够找到它们。

配置proto文件

基本配置

在proto文件中，除了常规的Hertz注解外，还需要添加openapiv3和google/api的引入：

syntax = "proto3";

package api;

option go_package = "server/cmd/api";

import "hz.proto";
import "openapiv3/annotations.proto";
import "google/api/annotations.proto";

字段注解

可以为字段添加openapiv3的详细注解，例如：

message LoginRequest {
  string code = 1[
    (api.vd) = "len($) > 0",
    (openapi.v3.property) = {
      min_length: 1;
    }
  ];
}

服务方法注解

服务方法需要同时添加Hertz和google.api的HTTP注解：

service apiService {
  rpc Login (LoginRequest) returns (LoginResponse) {
    option (api.post) = "/auth/login";
    option(google.api.http) = {
      post: "/auth/login"
    };
  }
}

生成文档

使用以下命令生成OpenAPI文档：

hz update -idl api.proto --protoc-plugins=openapi::./doc

常见问题解决

1. 生成的文档为空：检查是否缺少必要的proto文件引入或注解
2. 字段命名风格问题：默认会转换为PascalCase，如需保持snake_case，可添加naming=proto参数
3. 警告信息：某些警告可能来自protoc-gen-openapi插件，通常不影响文档生成

最佳实践

1. 文档版本控制：将生成的OpenAPI文档纳入版本控制系统
2. 持续集成：在CI流程中加入文档生成步骤
3. 文档验证：使用Swagger UI等工具验证生成的文档
4. 命名规范：保持proto字段命名与API文档命名的一致性

未来展望

Hertz社区正在开发更适配Hertz注解的swagger-generate工具，未来将提供更便捷的文档生成体验，无需额外配置google.api等注解。

总结

通过合理配置proto文件和正确使用protoc-gen-openapi插件，开发者可以在Hertz项目中轻松生成符合OpenAPI规范的API文档。虽然目前需要一些额外配置，但随着工具链的完善，这一过程将变得更加简单高效。建议开发者关注Hertz社区的最新动态，及时获取更好的文档生成解决方案。