From 4e4e02184a8d14ff75cd635cf1ae1396e4ed9100 Mon Sep 17 00:00:00 2001 From: Ricagraca Date: Wed, 24 Aug 2022 10:08:39 +0100 Subject: [PATCH 1/8] Replaced openapiv2 generator with openapi v3 using gnostic on buf generate --- _template/Makefile | 4 ++-- _template/api/proto/buf.yaml | 3 ++- .../v1/{{.Base.appName}}.proto | 21 +++++-------------- _template/tools.go | 2 +- 4 files changed, 10 insertions(+), 20 deletions(-) diff --git a/_template/Makefile b/_template/Makefile index d361b8aa..b8154a6d 100644 --- a/_template/Makefile +++ b/_template/Makefile @@ -83,7 +83,7 @@ GO_DEPENDENCIES = google.golang.org/protobuf/cmd/protoc-gen-go \ {{- if .Extensions.grpc.grpcGateway }} # additional dependencies for grpc-gateway GO_DEPENDENCIES += github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway \ - github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 + github.com/google/gnostic/cmd/protoc-gen-openapi {{- end }} define make-go-dependency @@ -106,7 +106,7 @@ protobreaking: api/proto/buf.lock bin/protoc-gen-buf-breaking ## Compares your c bin/buf breaking --against '.git#branch=main' generate: ## Generates code from protobuf files -generate: {{if .Extensions.grpc.grpcGateway}}bin/protoc-gen-grpc-gateway bin/protoc-gen-openapiv2{{end}} api/proto/buf.lock bin/protoc-gen-go bin/protoc-gen-go-grpc bin/protoc-gen-validate +generate: {{if .Extensions.grpc.grpcGateway}}bin/protoc-gen-grpc-gateway bin/protoc-gen-openapi{{end}} api/proto/buf.lock bin/protoc-gen-go bin/protoc-gen-go-grpc bin/protoc-gen-validate PATH=$(PWD)/bin:$$PATH buf generate {{- end }} diff --git a/_template/api/proto/buf.yaml b/_template/api/proto/buf.yaml index 4b0a2a28..f493e3ff 100644 --- a/_template/api/proto/buf.yaml +++ b/_template/api/proto/buf.yaml @@ -6,7 +6,7 @@ deps: - buf.build/envoyproxy/protoc-gen-validate - buf.build/googleapis/googleapis {{- if .Extensions.grpc.grpcGateway }} - - buf.build/grpc-ecosystem/grpc-gateway + - buf.build/gnostic/gnostic {{- end }} lint: use: @@ -14,3 +14,4 @@ lint: except: - RPC_RESPONSE_STANDARD_NAME - RPC_REQUEST_RESPONSE_UNIQUE + - IMPORT_NO_WEAK # required by gnostic for now. this way gen-go will not import _ "" broken packages diff --git a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto index 5034bfc2..133c6f88 100644 --- a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto +++ b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto @@ -9,34 +9,23 @@ import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto"; import "validate/validate.proto"; {{- if .Extensions.grpc.grpcGateway }} -import "protoc-gen-openapiv2/options/annotations.proto"; +// weak, otherwise gnostic imports broken imports for gen-go +// weak import: proto definition only adds options, no additional messages. +// buf:lint:ignore IMPORT_NO_WEAK +import weak "gnostic/openapi/v3/annotations.proto"; // Will not import _ "" in the gen-go files {{- end }} // Defines the import path that should be used to import the generated package, // and the package name. option go_package = "{{.Base.moduleName | replace `.git` ``}}/internal/pkg/pb;pb"; -{{- if .Extensions.grpc.grpcGateway }} -// These annotations are used when generating the OpenAPI file. -option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { - swagger: "2.0" - info: { - title: "{{.Base.appName}}-api" - version: "1.0" - description: "{{.Base.projectDescription}}" - } - schemes: HTTP - host: "localhost:8080" -}; -{{- end }} - service {{ .Base.appName | title | replace "-" "" }}Service { {{- if .Extensions.grpc.grpcGateway }} rpc GetExample(GetExampleRequest) returns (GetExampleResponse) { option (google.api.http) = { get: "/v1/example" }; - option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + option (gnostic.openapi.v3.operation) = { summary: "Get example response" description: "Returns an empty example response" tags: "example" diff --git a/_template/tools.go b/_template/tools.go index ae4564a4..9a6bb1ae 100644 --- a/_template/tools.go +++ b/_template/tools.go @@ -11,6 +11,6 @@ import ( _ "google.golang.org/protobuf/cmd/protoc-gen-go" {{- if .Extensions.grpc.grpcGateway }} _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway" - _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2" + _ "github.com/google/gnostic/cmd/protoc-gen-openapi" {{- end }} ) From 9ceead81b883abbc0fa29d7bc22c1c7a801b9e88 Mon Sep 17 00:00:00 2001 From: Ricagraca Date: Wed, 24 Aug 2022 10:40:16 +0100 Subject: [PATCH 2/8] Added if for no import on gateway grpc --- _template/api/proto/buf.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_template/api/proto/buf.yaml b/_template/api/proto/buf.yaml index f493e3ff..60b85182 100644 --- a/_template/api/proto/buf.yaml +++ b/_template/api/proto/buf.yaml @@ -14,4 +14,6 @@ lint: except: - RPC_RESPONSE_STANDARD_NAME - RPC_REQUEST_RESPONSE_UNIQUE +{{- if .Extensions.grpc.grpcGateway }} - IMPORT_NO_WEAK # required by gnostic for now. this way gen-go will not import _ "" broken packages +{{- end }} \ No newline at end of file From 008a109941c6b44ebc65b3d6d2603d35ce6dae33 Mon Sep 17 00:00:00 2001 From: Ricagraca Date: Wed, 24 Aug 2022 10:56:04 +0100 Subject: [PATCH 3/8] Added example document v3 --- .../v1/{{.Base.appName}}.proto | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto index 133c6f88..43573b01 100644 --- a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto +++ b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto @@ -19,6 +19,41 @@ import weak "gnostic/openapi/v3/annotations.proto"; // Will not import _ "" in t // and the package name. option go_package = "{{.Base.moduleName | replace `.git` ``}}/internal/pkg/pb;pb"; +{{- if .Extensions.grpc.grpcGateway }} +// These annotations are used when generating the OpenAPI file. +option (openapi.v3.document) = { + info: { + title: "Title from annotation"; + version: "Version from annotation"; + description: "Description from annotation"; + contact: { + name: "Contact Name"; + url: "https://github.com/google/gnostic"; + email: "gnostic@google.com"; + } + license: { + name: "Apache License"; + url: "https://github.com/google/gnostic/blob/master/LICENSE"; + } + } + components: { + security_schemes: { + additional_properties: [ + { + name: "BasicAuth"; + value: { + security_scheme: { + type: "http"; + scheme: "basic"; + } + } + } + ] + } + } +}; +{{- end }} + service {{ .Base.appName | title | replace "-" "" }}Service { {{- if .Extensions.grpc.grpcGateway }} rpc GetExample(GetExampleRequest) returns (GetExampleResponse) { From df939a3736ccf1d4a7781573fcebcae456574705 Mon Sep 17 00:00:00 2001 From: Ricagraca Date: Wed, 24 Aug 2022 11:09:12 +0100 Subject: [PATCH 4/8] Added document --- .../{{.Base.appName}}/v1/{{.Base.appName}}.proto | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto index 43573b01..dbd0be71 100644 --- a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto +++ b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto @@ -23,18 +23,9 @@ option go_package = "{{.Base.moduleName | replace `.git` ``}}/internal/pkg/pb;pb // These annotations are used when generating the OpenAPI file. option (openapi.v3.document) = { info: { - title: "Title from annotation"; - version: "Version from annotation"; - description: "Description from annotation"; - contact: { - name: "Contact Name"; - url: "https://github.com/google/gnostic"; - email: "gnostic@google.com"; - } - license: { - name: "Apache License"; - url: "https://github.com/google/gnostic/blob/master/LICENSE"; - } + title: "{{.Base.appName}}-api"; + version: "1.0"; + description: "{{.Base.projectDescription}}"; } components: { security_schemes: { From c4aa34809456425d9b5b590b4bd446c685fe93f6 Mon Sep 17 00:00:00 2001 From: Ricagraca Date: Wed, 24 Aug 2022 15:03:32 +0100 Subject: [PATCH 5/8] Added server host --- .../api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto | 4 ++++ embed_gen.go | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto index dbd0be71..ec572ace 100644 --- a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto +++ b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto @@ -42,6 +42,10 @@ option (openapi.v3.document) = { ] } } + servers : { + url: "http://localhost:8080"; + description: "Host Server" + } }; {{- end }} diff --git a/embed_gen.go b/embed_gen.go index a0bbbd11..1ebf7884 100644 --- a/embed_gen.go +++ b/embed_gen.go @@ -3,5 +3,5 @@ package gotemplate import "embed" -//go:embed _template _template/.azure-pipelines.yml _template/.dockerignore _template/.editorconfig _template/.githooks _template/.github _template/.gitignore _template/.gitlab-ci.yml _template/.golangci.yml +//go:embed _template _template/.azure-pipelines.yml _template/.dockerignore _template/.editorconfig _template/.githooks _template/.github _template/.gitignore _template/.gitlab-ci.yml _template/.golangci.yml _template/.vscode var FS embed.FS From 0a1892af4db04d728fa955d4e5a5e9be55f36457 Mon Sep 17 00:00:00 2001 From: Daniel Zwink Date: Fri, 14 Oct 2022 14:54:41 +0200 Subject: [PATCH 6/8] Remove vscode dir, fix broken merge commit --- embed_gen.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/embed_gen.go b/embed_gen.go index b0de708b..a0bbbd11 100644 --- a/embed_gen.go +++ b/embed_gen.go @@ -3,5 +3,5 @@ package gotemplate import "embed" -//go:embed _template _template/.azure-pipelines.yml _template/.dockerignore _template/.editorconfig _template/.githooks _template/.github _template/.gitignore _template/.gitlab-ci.yml _template/.golangci.yml _template/.vscode -var FS embed.FS \ No newline at end of file +//go:embed _template _template/.azure-pipelines.yml _template/.dockerignore _template/.editorconfig _template/.githooks _template/.github _template/.gitignore _template/.gitlab-ci.yml _template/.golangci.yml +var FS embed.FS From 13921f8ea2842bf8d76a68710ebd3169a17d7e8d Mon Sep 17 00:00:00 2001 From: Daniel Zwink Date: Fri, 4 Nov 2022 14:33:33 +0100 Subject: [PATCH 7/8] Fix openapi version update --- .../api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto | 2 +- _template/buf.gen.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto index ec572ace..8631b1fc 100644 --- a/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto +++ b/_template/api/proto/{{.Base.appName}}/v1/{{.Base.appName}}.proto @@ -21,7 +21,7 @@ option go_package = "{{.Base.moduleName | replace `.git` ``}}/internal/pkg/pb;pb {{- if .Extensions.grpc.grpcGateway }} // These annotations are used when generating the OpenAPI file. -option (openapi.v3.document) = { +option (gnostic.openapi.v3.document) = { info: { title: "{{.Base.appName}}-api"; version: "1.0"; diff --git a/_template/buf.gen.yaml b/_template/buf.gen.yaml index e62f9980..e98e9b31 100644 --- a/_template/buf.gen.yaml +++ b/_template/buf.gen.yaml @@ -10,7 +10,7 @@ plugins: - name: grpc-gateway out: internal/pkg/api/pb opt: paths=source_relative - - name: openapiv2 + - name: openapi out: api/openapi {{- end }} - name: validate From fe40b588a67c57f643e97a7758c0d8e72df57df8 Mon Sep 17 00:00:00 2001 From: Daniel Zwink Date: Fri, 4 Nov 2022 14:34:04 +0100 Subject: [PATCH 8/8] Remove global lint option since local is sufficient --- _template/api/proto/buf.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/_template/api/proto/buf.yaml b/_template/api/proto/buf.yaml index 60b85182..a0ecfa2c 100644 --- a/_template/api/proto/buf.yaml +++ b/_template/api/proto/buf.yaml @@ -14,6 +14,3 @@ lint: except: - RPC_RESPONSE_STANDARD_NAME - RPC_REQUEST_RESPONSE_UNIQUE -{{- if .Extensions.grpc.grpcGateway }} - - IMPORT_NO_WEAK # required by gnostic for now. this way gen-go will not import _ "" broken packages -{{- end }} \ No newline at end of file