refactor: 修改 protoc-gen-connect-openapi 并部分重构 (#10)

Author: kooksee

.github/workflows/go.yml

@@ -21,3 +21,16 @@ Package.resolved
 extensions/sample/generated
 /.proto
 /vendor
+/bin
+/proto-vendor
+
+# Go workspace file
+go.work
+
+redoc-static.html
+
+out
+dist
+
+coverage.out
+coverage.html

.gitignore

@@ -1,14 +1,20 @@
 builds:
   - main: ./main.go
-    id: protoc-gen-openapi
     binary: protoc-gen-openapi
-    skip: false
     goos:
       - linux
       - darwin
       - windows
     goarch:
       - amd64
+      - arm64
+    env:
+      - CGO_ENABLED=0
+    mod_timestamp: "{{ .CommitTimestamp }}"
+    ldflags:
+      - "-X '{{ .ModulePath }}/version.version={{ .Version }}'"
+      - "-X '{{ .ModulePath }}/version.commit={{ .Commit }}'"
+      - "-X '{{ .ModulePath }}/version.date={{ .CommitTimestamp }}'"
 archives:
   - name_template: "{{ .Binary }}-{{ .Tag }}-{{ .Os }}-{{ .Arch }}"
     format: tar.gz

.goreleaser.yaml

@@ -1,23 +1,16 @@
-test:
-	# since some tests call separately-built binaries, clear the cache to ensure all get run
-	go clean -testcache
-	go test ./... -v
-
 vet:
 	go vet ./...
 
-pb:
-	protobuild vendor
-
-pb_test:
-	protobuild -c protobuf_test.yaml vendor
-	protobuild -c protobuf_test.yaml gen
-
-install_gnostic:
-	go install github.com/google/gnostic/cmd/[email protected]
-
 protobuf:
 	protobuild vendor
 	protobuild gen
-	mv github.com/pubgo/protoc-gen-openapi/generator/service.pb.go ./generator
+	rm -rf generator
+	mv github.com/pubgo/protoc-gen-openapi/generator generator
 	rm -rf github.com
+
+protobuf_test:
+	protobuild vendor -c protobuf_auth_base.yaml
+	protobuild gen -c protobuf_auth_base.yaml
+
+install:
+	go install .

Makefile

@@ -1,67 +1,31 @@
 # protoc-gen-openapi
 
-> This directory contains a protoc plugin that generates an
-OpenAPI description for a REST API that corresponds to a
-Protocol Buffer service.
+- 本项目一个 protobuf openapi 插件的实现
+- 本项目早期参考了[protoc-gen-openapi](https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi), 由于 gnostic 长时间不更新，并发现了优秀的替代品[protoc-gen-connect-openapi](https://github.com/sudorandom/protoc-gen-connect-openapi),  现在基于[protoc-gen-connect-openapi](https://github.com/sudorandom/protoc-gen-connect-openapi) 做了部分修改
+- internal/converter 大部分都是来自于 protoc-gen-connect-openapi, copy.go 部分是自己的实现
 
-> This project is a simplification of the [google/gnostic](https://github.com/google/gnostic/tree/main/openapiv3) project, dedicated to providing a simple version of the protoc-gen-openapi
+## 为什么修改 protoc-gen-connect-openapi
+- protoc-gen-connect-openapi 刚好和本项目早期底层使用一致, 为本项目重构提供了很好的思路和想法
+- protoc-gen-connect-openapi 是为了 connect-go 生成 openapi 文档, 包含不少 connect 关键词
+- protoc-gen-connect-openapi 不支持 grpc service 级别的注解
+- protoc-gen-connect-openapi 针对企业内部业务级别的修改无法支持
 
-Installation:
+## 改动部分
 
-    go install github.com/pubgo/protoc-gen-openapi@latest
+- 使用原生的 [google.golang.org/protobuf/compiler/protogen](https://pkg.go.dev/google.golang.org/protobuf/compiler/protogen)
+- 添加了 grpc service 级别的注解 [service.proto](./proto/openapiv3/service.proto), [example](./examples/tests/openapiv3annotations/message.proto)
+- 添加了 [lava](https://github.com/pubgo/lava) 相关的 header 信息
+- 添加了 Error Code 定义 [error.proto](https://github.com/pubgo/funk/blob/master/proto/errorpb/errors.proto)
+- 使用 [protobuild](https://github.com/pubgo/protobuild) 进行 protobuf 构建和管理
+
+ ## Installation:
 
-Usage:
+    go install github.com/pubgo/protoc-gen-openapi@latest
 
-	protoc sample.proto -I=. --openapi_out=.
+## 使用
 
-This runs the plugin for a file named `sample.proto` which 
-refers to additional .proto files in the same directory as
-`sample.proto`. Output is written to the current directory.
+参考 `make protobuf_test`
 
-## options
+## 计划
 
-1. `version`: version number text, e.g. 1.2.3
-   - **default**: `0.0.1`
-2. `title`: name of the API
-   - **default**: empty string or service name if there is only one service
-3. `description`: description of the API
-   - **default**: empty string or service description if there is only one service
-4. `naming`: naming convention. Use "proto" for passing names directly from the proto files
-   - **default**: `json`
-   - `json`: will turn field `updated_at` to `updatedAt`
-   - `proto`: keep field `updated_at` as it is
-5. `fq_schema_naming`: schema naming convention. If "true", generates fully-qualified schema names by prefixing them with the proto message package name
-   - **default**: false
-   - `false`: keep message `Book` as it is
-   - `true`: turn message `Book` to `google.example.library.v1.Book`, it is useful when there are same named message in different package
-6. `enum_type`: type for enum serialization. Use "string" for string-based serialization
-   - **default**: `integer`
-   - `integer`: setting type to `integer`
-      ```yaml
-      schema:
-        type: integer
-        format: enum
-      ```
-   - `string`: setting type to `string`, and list available values in `enum`
-      ```yaml
-      schema:
-        enum:
-          - UNKNOWN_KIND
-          - KIND_1
-          - KIND_2
-        type: string
-        format: enum
-      ```
-7. `depth`: depth of recursion for circular messages
-   - **default**: 2, this depth only used in query parameters, usually 2 is enough
-8. `default_response`: add default response. If "true", automatically adds a default response to operations which use the google.rpc.Status message.
-   Useful if you use envoy or grpc-gateway to transcode as they use this type for their default error responses.
-   - **default**: true, this option will add this default response for each method as following:
-      ```yaml
-      default:
-        description: Default error response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/google.rpc.Status'
-      ```
+- 长期兼容 gnostic, 兼容 protoc-gen-connect-openapi, 后期会进行重构

README.md

@@ -0,0 +1,15 @@
+openapi: 3.1.0
+info:
+  title: MyProject
+  description: "My Project Description"
+  version: v1.0.0
+# 1) Define the security scheme type (HTTP bearer)
+components:
+  securitySchemes:
+    bearerAuth: # arbitrary name for the security scheme
+      type: http
+      scheme: bearer
+      bearerFormat: JWT # optional, arbitrary value for documentation purposes
+# 2) Apply the security globally to all operations
+security:
+  - bearerAuth: [] # use the same name as above

auth-base.yaml

@@ -1,3 +1,5 @@
 package docs
 
-// https://github.com/kollalabs/protoc-gen-openapi/tree/main
+// https://github.com/kollalabs/protoc-gen-openapi
+// https://github.com/google/gnostic
+// https://github.com/sudorandom/protoc-gen-connect-openapi

docs/_docs.go

@@ -0,0 +1,83 @@
+// Example description, used in
+syntax = "proto3";
+
+package example.basic;
+
+import "buf/validate/validate.proto";
+import "openapiv3/annotations.proto";
+
+option go_package = "google.golang.org/grpc/examples/helloworld/helloworld";
+option java_multiple_files = true;
+option java_outer_classname = "HelloWorldProto";
+option java_package = "io.grpc.examples.helloworld";
+// Full list of options can be seen here: https://github.com/google/gnostic/blob/main/openapiv3/openapi.v3.proto
+// File options (openapi.v3.document): Document message
+// Method options (openapi.v3.operation): Operation message
+// Message options (openapi.v3.schema): Schema message
+// Field options (openapi.v3.property): Schema message
+option (openapi.v3.document) = {
+  info: {
+    title: "Hello World"
+    version: "v2"
+    description: "This is a service which says hello to you!"
+    contact: {
+      name: "Ein"
+      url: "https://github.com/sudorandom/protoc-gen-connect-openapi"
+      email: "[email protected]"
+    }
+    license: {
+      name: "MIT License"
+      url: "https://github.com/sudorandom/protoc-gen-connect-openapi/blob/master/LICENSE"
+    }
+  }
+  components: {
+    security_schemes: {
+      additional_properties: [
+        {
+          name: "BasicAuth"
+          value: {
+            security_scheme: {
+              type: "http"
+              scheme: "basic"
+            }
+          }
+        }
+      ]
+    }
+  }
+};
+
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc SayHello(HelloRequest) returns (HelloReply) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+    option (openapi.v3.operation).description = "This is a description just for OpenAPI";
+  }
+
+  // Writes a greeting (has side effects)
+  rpc WriteHello(HelloRequest) returns (Response) {}
+}
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1 [
+    (buf.validate.field).string = {
+      min_len: 3
+      max_len: 100
+    },
+    (openapi.v3.property) = {
+      example: {yaml: "Ein"}
+    }
+  ];
+  uint32 hello_count = 2 [(buf.validate.field).uint32.lt = 42];
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}
+
+message Response {
+  repeated HelloReply repl = 1;
+}