使用 protoc-gen-openapi 无法生成 api 文档

jjeejj commented 3 weeks ago

版本信息：

hz version v0.8.1 protoc --version
libprotoc 25.3

go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest go: downloading github.com/google/gnostic v0.7.0

参考文档地址

https://www.cloudwego.io/zh/docs/hertz/tutorials/toolkit/more-feature/plugin/#protoc-%E6%8F%92%E4%BB%B6%E6%8B%93%E5%B1%95

idl 示范

api.proto

syntax = "proto3";

package api;

option go_package = "server/cmd/api";

import "hz.proto";

message LoginRequest {
  string code = 1[(api.vd) = "len($) > 0"];
}

message LoginResponse {
  string token = 1;
  int64 expired_at = 2[(api.body) = "expired_at"];
}

message UserInfo{
   int64 account_id = 1;
   string username = 2;
   int64 phone_number = 3;
   string avatar_url = 4;
}

message GetUserInfoRequest{}

message UpdateUserRequest{
    string username = 1;
    int64 phone_number = 2;
}

message UpdateUserResponse{
}

service apiService {
  rpc Login (LoginRequest) returns (LoginResponse) {option (api.post) = "/auth/login";}
  rpc GetUserInfo (GetUserInfoRequest) returns (UserInfo) {option (api.get) = "/auth/info";}
}

执行命令： hz update -idl api.proto --protoc-plugins=openapi::./doc 后在 doc 目录下生成的 openapi.yaml 文件内容只有

# Generated with protoc-gen-openapi
# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi

openapi: 3.0.3
info:
    title: ""
    version: 0.0.1
paths: {}
components:
    schemas: {}

EZ4Jam1n commented 2 weeks ago

@jjeejj 你好，通过hz集成protoc-gen-openapi来生成openapi文档时，你还需要做以下工作：

创建proto文件时，引入openapiv3/annotations.proto和google/api/annotations.proto，运行时通过-I参数指定引入路径
你可以从以下仓库搜集： protobuf/src/google/protobuf at main · protocolbuffers/protobuf googleapis/google/api at master · googleapis/googleapis gnostic/openapiv3 at main · google/gnostic 完整的引入如下所示：
```
google
├── api
│   ├── annotations.proto
│   └── http.proto
├── protobuf
│   ├── any.proto
│   └── descriptor.proto
openapiv3
├── annotations.proto
└── OpenAPIv3.proto
```
编写 idl 文件时，写入 openapi 相关注解，更多的例子可以查看protoc-gen-openapi/examples 以下是你的proto的一个示例：
```
syntax = "proto3";
```

package api;

option go_package = "server/cmd/api";

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

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

message LoginResponse { string token = 1; int64 expired_at = 2[(api.body) = "expired_at"]; }

message UserInfo{ int64 account_id = 1; string username = 2; int64 phone_number = 3; string avatar_url = 4; }

message GetUserInfoRequest{}

message UpdateUserRequest{ string username = 1; int64 phone_number = 2; }

message UpdateUserResponse{ }

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


此时可以生成正确的openapi文档

---
同时，我们目前正在开发和hz注解适配的openapi文档生成插件，你可以关注[swagger-generate](https://github.com/hertz-contrib/swagger-generate)这个仓库，很快会上线，敬请关注。

jjeejj commented 2 weeks ago

可以正常生成的，就是有一个警告

现在还是有些麻烦，需要额外配置一些选项。期待 swagger-generate 直接根据 hz 的注解生成

jjeejj commented 2 weeks ago

@EZ4Jam1n 另外生成的 api 文档会自动把请求参数和响应结果转换为驼峰的格式，有办法生成 snake 下划线连接的格式吗？

EZ4Jam1n commented 2 weeks ago

@EZ4Jam1n 另外生成的 api 文档会自动把请求参数和响应结果转换为驼峰的格式，有办法生成 snake 下划线连接的格式吗？

protoc-gen-openapi 是基于 protoc 的插件模式生成的，而 protoc 遵循 Go 的命名约定，会将 Protobuf 的字段名从 snake_case 转换为 PascalCase

jjeejj commented 2 weeks ago

@EZ4Jam1n 另外生成的 api 文档会自动把请求参数和响应结果转换为驼峰的格式，有办法生成 snake 下划线连接的格式吗？

protoc-gen-openapi 是基于 protoc 的插件模式生成的，而 protoc 遵循 Go 的命名约定，会将 Protobuf 的字段名从 snake_case 转换为 PascalCase

有没有办法不转换？使用 snake_case

FGYFFFF commented 2 weeks ago

可以正常生成的，就是有一个警告

现在还是有些麻烦，需要额外配置一些选项。期待 swagger-generate 直接根据 hz 的注解生成

目前规范不太一样，不太好直接转换

cloudwego / hertz