From bb2fe4f226170f24fbb35e1f2b900c4cfbd5530d Mon Sep 17 00:00:00 2001 From: Johan Brandhorst Date: Sun, 24 May 2020 22:36:03 +0100 Subject: [PATCH] all: rename protoc-gen-swagger to protoc-gen-openapiv2 Fixes #675 --- .github/ISSUE_TEMPLATE.md | 4 +- .goreleaser.yml | 6 +- BUILD | 2 +- Makefile | 44 +- README.md | 22 +- bin/.gitignore | 2 +- docs/_docs/aws.md | 2 +- docs/_docs/customizingyourgateway.md | 2 +- docs/_docs/cygwin.md | 4 +- docs/_docs/faq.md | 2 +- docs/_docs/features.md | 2 +- docs/_docs/usegotemplates.md | 16 +- docs/_docs/v2-migration.md | 29 +- examples/internal/README.md | 2 +- .../a_bit_of_everything_service.spec.js | 2 +- .../internal/browser/echo_service.spec.js | 2 +- examples/internal/browser/gulpfile.js | 2 +- examples/internal/browser/index.html | 2 +- .../internal/clients/responsebody/BUILD.bazel | 1 - .../cmd/example-gateway-server/main.go | 4 +- examples/internal/gateway/handlers.go | 6 +- examples/internal/gateway/main.go | 8 +- examples/internal/integration/main_test.go | 4 +- examples/internal/proto/examplepb/BUILD.bazel | 14 +- .../proto/examplepb/a_bit_of_everything.pb.go | 1366 ++++++++--------- .../proto/examplepb/a_bit_of_everything.proto | 38 +- internal/descriptor/registry.go | 34 +- .../BUILD.bazel | 6 +- .../defs.bzl | 58 +- .../internal/genopenapi}/BUILD.bazel | 8 +- .../internal/genopenapi/doc.go | 2 + .../internal/genopenapi}/generator.go | 58 +- .../internal/genopenapi}/helpers.go | 2 +- .../internal/genopenapi}/helpers_go111_old.go | 2 +- .../internal/genopenapi}/template.go | 352 ++--- .../internal/genopenapi}/template_test.go | 262 ++-- .../internal/genopenapi}/types.go | 100 +- .../main.go | 16 +- .../main_test.go | 20 +- .../options/BUILD.bazel | 4 +- .../options/annotations.pb.go | 241 +++ .../options/annotations.proto | 6 +- .../options/openapiv2.pb.go | 1107 ++++++------- .../options/openapiv2.proto | 43 +- protoc-gen-swagger/internal/genswagger/doc.go | 2 - protoc-gen-swagger/options/annotations.pb.go | 240 --- runtime/mux.go | 2 +- 47 files changed, 2095 insertions(+), 2058 deletions(-) rename {protoc-gen-swagger => protoc-gen-openapiv2}/BUILD.bazel (86%) rename {protoc-gen-swagger => protoc-gen-openapiv2}/defs.bzl (79%) rename {protoc-gen-swagger/internal/genswagger => protoc-gen-openapiv2/internal/genopenapi}/BUILD.bazel (88%) create mode 100644 protoc-gen-openapiv2/internal/genopenapi/doc.go rename {protoc-gen-swagger/internal/genswagger => protoc-gen-openapiv2/internal/genopenapi}/generator.go (81%) rename {protoc-gen-swagger/internal/genswagger => protoc-gen-openapiv2/internal/genopenapi}/helpers.go (86%) rename {protoc-gen-swagger/internal/genswagger => protoc-gen-openapiv2/internal/genopenapi}/helpers_go111_old.go (87%) rename {protoc-gen-swagger/internal/genswagger => protoc-gen-openapiv2/internal/genopenapi}/template.go (84%) rename {protoc-gen-swagger/internal/genswagger => protoc-gen-openapiv2/internal/genopenapi}/template_test.go (91%) rename {protoc-gen-swagger/internal/genswagger => protoc-gen-openapiv2/internal/genopenapi}/types.go (72%) rename {protoc-gen-swagger => protoc-gen-openapiv2}/main.go (92%) rename {protoc-gen-swagger => protoc-gen-openapiv2}/main_test.go (92%) rename {protoc-gen-swagger => protoc-gen-openapiv2}/options/BUILD.bazel (94%) create mode 100644 protoc-gen-openapiv2/options/annotations.pb.go rename {protoc-gen-swagger => protoc-gen-openapiv2}/options/annotations.proto (92%) rename {protoc-gen-swagger => protoc-gen-openapiv2}/options/openapiv2.pb.go (57%) rename {protoc-gen-swagger => protoc-gen-openapiv2}/options/openapiv2.proto (95%) delete mode 100644 protoc-gen-swagger/internal/genswagger/doc.go delete mode 100644 protoc-gen-swagger/options/annotations.pb.go diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 9cb92f9eecc..23f0f71a680 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -6,11 +6,11 @@ ```sh go get -u github.com/grpc-ecosystem/grpc-gateway ``` -- [ ] Delete the `protoc-gen-grpc-gateway` and `protoc-gen-swagger` binary from your `PATH`, +- [ ] Delete the `protoc-gen-grpc-gateway` and `protoc-gen-openapiv2` binary from your `PATH`, and reinstall the latest versions: ```sh go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway - go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger + go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv2 ``` ## I still have a problem! diff --git a/.goreleaser.yml b/.goreleaser.yml index bcc63e544d3..ffbe2430c71 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -10,9 +10,9 @@ builds: - windows goarch: - amd64 - - main: ./protoc-gen-swagger/main.go - id: protoc-gen-swagger - binary: protoc-gen-swagger + - main: ./protoc-gen-openapiv2/main.go + id: protoc-gen-openapiv2 + binary: protoc-gen-openapiv2 env: - CGO_ENABLED=0 goos: diff --git a/BUILD b/BUILD index f649e124b47..d0b40ee0274 100644 --- a/BUILD +++ b/BUILD @@ -21,6 +21,6 @@ package_group( name = "generators", packages = [ "//protoc-gen-grpc-gateway/...", - "//protoc-gen-swagger/...", + "//protoc-gen-openapiv2/...", ], ) diff --git a/Makefile b/Makefile index 031d5b141ca..57e46b3c4f4 100644 --- a/Makefile +++ b/Makefile @@ -7,14 +7,14 @@ GO_PLUGIN=bin/protoc-gen-go GO_PROTOBUF_REPO=github.com/golang/protobuf GO_PLUGIN_PKG=$(GO_PROTOBUF_REPO)/protoc-gen-go GO_PTYPES_ANY_PKG=$(GO_PROTOBUF_REPO)/ptypes/any -SWAGGER_PLUGIN=bin/protoc-gen-swagger -SWAGGER_PLUGIN_SRC= ./internal/utilities/doc.go \ +OPENAPI_PLUGIN=bin/protoc-gen-openapiv2 +OPENAPI_PLUGIN_SRC= ./internal/utilities/doc.go \ ./internal/utilities/pattern.go \ ./internal/utilities/trie.go \ - protoc-gen-swagger/internal/genswagger/generator.go \ - protoc-gen-swagger/internal/genswagger/template.go \ - protoc-gen-swagger/main.go -SWAGGER_PLUGIN_PKG=./protoc-gen-swagger + protoc-gen-openapiv2/internal/genopenapi/generator.go \ + protoc-gen-openapiv2/internal/genopenapi/template.go \ + protoc-gen-openapiv2/main.go +OPENAPI_PLUGIN_PKG=./protoc-gen-openapiv2 GATEWAY_PLUGIN=bin/protoc-gen-grpc-gateway GATEWAY_PLUGIN_PKG=./protoc-gen-grpc-gateway GATEWAY_PLUGIN_SRC= ./internal/utilities/doc.go \ @@ -38,12 +38,12 @@ GATEWAY_PLUGIN_SRC= ./internal/utilities/doc.go \ internal/httprule/types.go \ protoc-gen-grpc-gateway/main.go GATEWAY_PLUGIN_FLAGS?= -SWAGGER_PLUGIN_FLAGS?= +OPENAPI_PLUGIN_FLAGS?= GOOGLEAPIS_DIR=third_party/googleapis OUTPUT_DIR=_output -OPENAPIV2_PROTO=protoc-gen-swagger/options/openapiv2.proto protoc-gen-swagger/options/annotations.proto +OPENAPIV2_PROTO=protoc-gen-openapiv2/options/openapiv2.proto protoc-gen-openapiv2/options/annotations.proto OPENAPIV2_GO=$(OPENAPIV2_PROTO:.proto=.pb.go) ADDITIONAL_GW_FLAGS= @@ -51,10 +51,10 @@ ifneq "$(GATEWAY_PLUGIN_FLAGS)" "" ADDITIONAL_GW_FLAGS=,$(GATEWAY_PLUGIN_FLAGS) endif ADDITIONAL_SWG_FLAGS= -ifneq "$(SWAGGER_PLUGIN_FLAGS)" "" - ADDITIONAL_SWG_FLAGS=,$(SWAGGER_PLUGIN_FLAGS) +ifneq "$(OPENAPI_PLUGIN_FLAGS)" "" + ADDITIONAL_SWG_FLAGS=,$(OPENAPI_PLUGIN_FLAGS) endif -SWAGGER_EXAMPLES=examples/internal/proto/examplepb/echo_service.proto \ +OPENAPI_EXAMPLES=examples/internal/proto/examplepb/echo_service.proto \ examples/internal/proto/examplepb/a_bit_of_everything.proto \ examples/internal/proto/examplepb/wrappers.proto \ examples/internal/proto/examplepb/stream.proto \ @@ -78,7 +78,7 @@ HELLOWORLD=examples/internal/helloworld/helloworld.proto EXAMPLE_SVCSRCS=$(EXAMPLES:.proto=.pb.go) EXAMPLE_GWSRCS=$(EXAMPLES:.proto=.pb.gw.go) -EXAMPLE_SWAGGERSRCS=$(SWAGGER_EXAMPLES:.proto=.swagger.json) +EXAMPLE_OPENAPISRCS=$(OPENAPI_EXAMPLES:.proto=.swagger.json) EXAMPLE_DEPS=examples/internal/proto/pathenum/path_enum.proto examples/internal/proto/sub/message.proto examples/internal/proto/sub2/message.proto EXAMPLE_DEPSRCS=$(EXAMPLE_DEPS:.proto=.pb.go) @@ -153,8 +153,8 @@ $(OPENAPIV2_GO): $(OPENAPIV2_PROTO) $(GO_PLUGIN) $(GATEWAY_PLUGIN): $(GATEWAY_PLUGIN_SRC) go build -o $@ $(GATEWAY_PLUGIN_PKG) -$(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC) $(OPENAPIV2_GO) - go build -o $@ $(SWAGGER_PLUGIN_PKG) +$(OPENAPI_PLUGIN): $(OPENAPI_PLUGIN_SRC) $(OPENAPIV2_GO) + go build -o $@ $(OPENAPI_PLUGIN_PKG) $(EXAMPLE_SVCSRCS): $(GO_PLUGIN) $(EXAMPLES) protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GO_PLUGIN) --go_out=plugins=grpc,paths=source_relative:. $(EXAMPLES) @@ -177,9 +177,9 @@ $(EXAMPLE_GWSRCS): $(GATEWAY_PLUGIN) $(EXAMPLES) protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GATEWAY_PLUGIN) --grpc-gateway_out=logtostderr=true,allow_repeated_fields_in_body=true,paths=source_relative$(ADDITIONAL_GW_FLAGS):. $(EXAMPLES) -$(EXAMPLE_SWAGGERSRCS): ADDITIONAL_SWG_FLAGS:=$(ADDITIONAL_SWG_FLAGS),grpc_api_configuration=examples/internal/proto/examplepb/unannotated_echo_service.yaml -$(EXAMPLE_SWAGGERSRCS): $(SWAGGER_PLUGIN) $(SWAGGER_EXAMPLES) - protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(SWAGGER_PLUGIN) --swagger_out=logtostderr=true,allow_repeated_fields_in_body=true,use_go_templates=true$(ADDITIONAL_SWG_FLAGS):. $(SWAGGER_EXAMPLES) +$(EXAMPLE_OPENAPISRCS): ADDITIONAL_SWG_FLAGS:=$(ADDITIONAL_SWG_FLAGS),grpc_api_configuration=examples/internal/proto/examplepb/unannotated_echo_service.yaml +$(EXAMPLE_OPENAPISRCS): $(OPENAPI_PLUGIN) $(OPENAPI_EXAMPLES) + protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(OPENAPI_PLUGIN) --openapiv2_out=logtostderr=true,allow_repeated_fields_in_body=true,use_go_templates=true$(ADDITIONAL_SWG_FLAGS):. $(OPENAPI_EXAMPLES) $(HELLOWORLD_SVCSRCS): $(GO_PLUGIN) $(HELLOWORLD) protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GO_PLUGIN) --go_out=plugins=grpc,paths=source_relative:. $(HELLOWORLD) @@ -210,7 +210,7 @@ $(RESPONSE_BODY_EXAMPLE_SRCS): $(RESPONSE_BODY_EXAMPLE_SPEC) @rm -f $(EXAMPLE_CLIENT_DIR)/responsebody/README.md \ $(EXAMPLE_CLIENT_DIR)/responsebody/git_push.sh -examples: $(EXAMPLE_DEPSRCS) $(EXAMPLE_SVCSRCS) $(EXAMPLE_GWSRCS) $(EXAMPLE_SWAGGERSRCS) $(EXAMPLE_CLIENT_SRCS) $(HELLOWORLD_SVCSRCS) $(HELLOWORLD_GWSRCS) +examples: $(EXAMPLE_DEPSRCS) $(EXAMPLE_SVCSRCS) $(EXAMPLE_GWSRCS) $(EXAMPLE_OPENAPISRCS) $(EXAMPLE_CLIENT_SRCS) $(HELLOWORLD_SVCSRCS) $(HELLOWORLD_GWSRCS) testproto: $(RUNTIME_TEST_SRCS) $(APICONFIG_SRCS) test: examples testproto go test -short -race ./... @@ -233,20 +233,20 @@ lint: golint --set_exit_status ./runtime golint --set_exit_status ./internal/utilities/... golint --set_exit_status ./protoc-gen-grpc-gateway/... - golint --set_exit_status ./protoc-gen-swagger/... + golint --set_exit_status ./protoc-gen-openapiv2/... go vet ./runtime || true go vet ./internal/utilities/... go vet ./protoc-gen-grpc-gateway/... - go vet ./protoc-gen-swagger/... + go vet ./protoc-gen-openapiv2/... clean: - rm -f $(GATEWAY_PLUGIN) $(SWAGGER_PLUGIN) + rm -f $(GATEWAY_PLUGIN) $(OPENAPI_PLUGIN) distclean: clean rm -f $(GO_PLUGIN) realclean: distclean rm -f $(EXAMPLE_SVCSRCS) $(EXAMPLE_DEPSRCS) rm -f $(EXAMPLE_GWSRCS) - rm -f $(EXAMPLE_SWAGGERSRCS) + rm -f $(EXAMPLE_OPENAPISRCS) rm -f $(EXAMPLE_CLIENT_SRCS) rm -f $(HELLOWORLD_SVCSRCS) rm -f $(HELLOWORLD_GWSRCS) diff --git a/README.md b/README.md index 6940d2cb0eb..e3f220b5d6c 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ package tools import ( _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway" - _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-swagger" + _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2" _ "github.com/golang/protobuf/protoc-gen-go" ) ``` @@ -67,14 +67,14 @@ Run `go mod tidy` to resolve the versions. Install by running ```sh $ go install \ github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway \ - github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-swagger \ + github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 \ github.com/golang/protobuf/protoc-gen-go ``` This will place three binaries in your `$GOBIN`; * `protoc-gen-grpc-gateway` -* `protoc-gen-swagger` +* `protoc-gen-openapiv2` * `protoc-gen-go` Make sure that your `$GOBIN` is in your `$PATH`. @@ -130,7 +130,7 @@ annotation to your .proto file See [a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto) for examples of more annotations you can add to customize gateway behavior - and generated Swagger output. + and generated OpenAPI output. If you do not want to modify the proto file for use with grpc-gateway you can alternatively use an external @@ -243,10 +243,10 @@ annotation to your .proto file } ``` -7. (Optional) Generate swagger definitions using `protoc-gen-swagger` +7. (Optional) Generate OpenAPI definitions using `protoc-gen-openapiv2` ```sh - protoc -I. --swagger_out=logtostderr=true:./gen/swagger your/service/v1/your_service.proto + protoc -I. --openapiv2_out=logtostderr=true:./gen/openapiv2 your/service/v1/your_service.proto ``` ## Video intro @@ -266,7 +266,7 @@ example: ```sh --grpc-gateway_out=logtostderr=true,repeated_path_param_separator=ssv:. ---swagger_out=logtostderr=true,repeated_path_param_separator=ssv:. +--openapiv2_out=logtostderr=true,repeated_path_param_separator=ssv:. ``` `protoc-gen-grpc-gateway` supports custom mapping from Protobuf `import` to @@ -281,12 +281,12 @@ useful to pass the request-scoped context between the gateway and the gRPC servi logging. You can give these flags together with parameters above. Run `protoc-gen-grpc-gateway --help` for more details about the flags. -Similarly, `protoc-gen-swagger` supports command-line flags to control Swagger +Similarly, `protoc-gen-openapiv2` supports command-line flags to control OpenAPI output (for example, `json_names_for_fields` to output JSON names for fields -instead of protobuf names). Run `protoc-gen-swagger --help` for more flag -details. Further Swagger customization is possible by annotating your `.proto` +instead of protobuf names). Run `protoc-gen-openapiv2 --help` for more flag +details. Further OpenAPI customization is possible by annotating your `.proto` files with options from -[openapiv2.proto](protoc-gen-swagger/options/openapiv2.proto) - see +[openapiv2.proto](protoc-gen-openapiv2/options/openapiv2.proto) - see [a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto) for examples. diff --git a/bin/.gitignore b/bin/.gitignore index f20d08cf066..26df9ea603b 100644 --- a/bin/.gitignore +++ b/bin/.gitignore @@ -1,3 +1,3 @@ /protoc-gen-go /protoc-gen-grpc-gateway -/protoc-gen-swagger +/protoc-gen-openapiv2 diff --git a/docs/_docs/aws.md b/docs/_docs/aws.md index 96e98c089b6..33d3a51cbf6 100644 --- a/docs/_docs/aws.md +++ b/docs/_docs/aws.md @@ -4,7 +4,7 @@ category: documentation # AWS -## Import swagger documentation into AWS API Gateway +## Import OpenAPI documentation into AWS API Gateway The AWS API gateway service allows importing of an OpenAPI specification to create a REST API. The process is very straightforward and can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html). Here are some tips to consider when importing the documentation: diff --git a/docs/_docs/customizingyourgateway.md b/docs/_docs/customizingyourgateway.md index 8528a4a4fc5..805db6afe64 100644 --- a/docs/_docs/customizingyourgateway.md +++ b/docs/_docs/customizingyourgateway.md @@ -279,7 +279,7 @@ mux := runtime.NewServeMux( The signature of the handler is much more rigid because we need to know the structure of the error payload to properly -encode the "chunk" schema into a Swagger/OpenAPI spec. +encode the "chunk" schema into an OpenAPI spec. So the function must return a `*runtime.StreamError`. The handler can choose to omit some fields and can filter/transform the original diff --git a/docs/_docs/cygwin.md b/docs/_docs/cygwin.md index 5e0a37fafa6..db2170877bb 100644 --- a/docs/_docs/cygwin.md +++ b/docs/_docs/cygwin.md @@ -34,7 +34,7 @@ From an elevated cmd.exe prompt set the GOPATH variable in windows and add the ` Then `go get -u -v` the following packages: go get -u -v github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway - go get -u -v github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger + go get -u -v github.com/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv2 go get -u -v github.com/golang/protobuf/protoc-gen-go This will probably fail with similar output. @@ -62,7 +62,7 @@ Adjust steps 3, 5 and 7 like this. protoc expects native windows paths. protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --go_out=plugins=grpc:. ./path/to/your_service.proto protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --grpc-gateway_out=logtostderr=true:. ./path/to/your_service.proto - protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --swagger_out=logtostderr=true:. ./path/to/your_service.proto + protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --openapiv2_out=logtostderr=true:. ./path/to/your_service.proto Then `cd` into the directory where your entry-point `main.go` file is located and run diff --git a/docs/_docs/faq.md b/docs/_docs/faq.md index 348f77387b7..30e34011428 100644 --- a/docs/_docs/faq.md +++ b/docs/_docs/faq.md @@ -33,7 +33,7 @@ e.g. https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/interna AFAIK, no. But it should not be a big issue because the reverse-proxy which grpc-gateway generates usually works as an independent process and communicates with your gRPC server over TCP or a unix-domain socket. -## Why are the models in the swagger specification prefixed with the last part of the proto package name? +## Why are the models in the OpenAPI specification prefixed with the last part of the proto package name? The reason to generate the prefixes is that we don't have a guaranteed unique namespace. If two packages produce different Foo messages then we will have trouble. diff --git a/docs/_docs/features.md b/docs/_docs/features.md index 1bead42e17e..a137a289ffe 100644 --- a/docs/_docs/features.md +++ b/docs/_docs/features.md @@ -12,7 +12,7 @@ category: documentation * Enum fields in path parameter (including repeated enum fields). * Mapping streaming APIs to newline-delimited JSON streams * Mapping HTTP headers with `Grpc-Metadata-` prefix to gRPC metadata (prefixed with `grpcgateway-`) -* Optionally emitting API definition for [Swagger](http://swagger.io). +* Optionally emitting API definition for [OpenAPI](http://swagger.io). * Setting [gRPC timeouts](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md) through inbound HTTP `Grpc-Timeout` header. * Partial support for [gRPC API Configuration](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config) files as an alternative to annotation. diff --git a/docs/_docs/usegotemplates.md b/docs/_docs/usegotemplates.md index 68649b2f21a..2bca1ab17f8 100644 --- a/docs/_docs/usegotemplates.md +++ b/docs/_docs/usegotemplates.md @@ -16,10 +16,10 @@ as: By default this function is turned off, so if you want to use it you have to set the `use_go_templates` flag to true inside of the -`swagger_out` flag. +`openapiv2_out` flag. ```shell ---swagger_out=use_go_templates=true:. +--openapiv2_out=use_go_templates=true:. ``` ### Example script @@ -30,7 +30,7 @@ Example of a bash script with the `use_go_templates` flag set to true: $ protoc -I. \ --go_out=plugins=grpc:. \ --grpc-gateway_out=logtostderr=true:. \ - --swagger_out=logtostderr=true,use_go_templates=true:. \ + --openapiv2_out=logtostderr=true,use_go_templates=true:. \ path/to/my/proto/v1/myproto.proto ``` @@ -80,19 +80,19 @@ The content of `tables.md`: | {{.Number}} | {{.Name}} | {{if eq .Label.String "LABEL_REPEATED"}}[]{{end}}{{.Type}} | {{fieldcomments .Message .}} | {{end}} ``` -## Swagger output +## OpenAPI output ### SwaggerUI -This is how the swagger file would be rendered in [SwaggerUI](https://swagger.io/tools/swagger-ui/) +This is how the OpenAPI file would be rendered in [Swagger UI](https://swagger.io/tools/swagger-ui/) -![Screenshot swaggerfile in SwaggerUI](../_imgs/gotemplates/swaggerui.png) +![Screenshot OpenAPI file in SwaggerUI](../_imgs/gotemplates/swaggerui.png) ### Postman -This is how the swagger file would be rendered in [Postman](https://www.getpostman.com/) +This is how the OpenAPI file would be rendered in [Postman](https://www.getpostman.com/) -![Screenshot swaggerfile in Postman](../_imgs/gotemplates/postman.png) +![Screenshot OpenAPI file in Postman](../_imgs/gotemplates/postman.png) For a more detailed example of a protofile that has Go templates enabled, [see the examples](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/use_go_template.proto). diff --git a/docs/_docs/v2-migration.md b/docs/_docs/v2-migration.md index fde14f82124..a198ad4e60a 100644 --- a/docs/_docs/v2-migration.md +++ b/docs/_docs/v2-migration.md @@ -11,6 +11,31 @@ information on all changes that were made specifically to v2. The following behavioural defaults have been changed: +## protoc-gen-swagger has been renamed protoc-gen-openapiv2 + +See +[the original issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/675) +for more information. Apart from the new name, the only real +difference to users will be a slightly different proto annotation: + +```protobuf +import "protoc-gen-openapiv2/options/annotations.proto"; +``` +instead of +```protobuf +import "protoc-gen-swagger/options/annotations.proto"; +``` +and +```protobuf +option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { +``` +instead of +```protobuf +option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = { +``` + +The bazel rule has been renamed `protoc_gen_openapiv2`. + ## We now use the camelCase JSON names by default See [the original issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/375) @@ -33,10 +58,10 @@ mux := runtime.NewServeMux( ) ``` -To change the swagger generator behaviour to match, set `json_names_for_fields=false` when generating: +To change the OpenAPI generator behaviour to match, set `json_names_for_fields=false` when generating: ```shell ---swagger_out=json_names_for_fields=false:./gen/swagger path/to/my/proto/v1/myproto.proto +--openapiv2_out=json_names_for_fields=false:./gen/openapiv2 path/to/my/proto/v1/myproto.proto ``` If using the Bazel rule, set `json_names_for_fields=False`. diff --git a/examples/internal/README.md b/examples/internal/README.md index 4a5039afc1a..55a1234d694 100644 --- a/examples/internal/README.md +++ b/examples/internal/README.md @@ -26,7 +26,7 @@ Then you can use curl or a browser to test: ```bash # List all apis -$ curl http://localhost:8080/swagger/echo_service.swagger.json +$ curl http://localhost:8080/openapiv2/echo_service.swagger.json # Visit the apis $ curl -XPOST http://localhost:8080/v1/example/echo/foo diff --git a/examples/internal/browser/a_bit_of_everything_service.spec.js b/examples/internal/browser/a_bit_of_everything_service.spec.js index 21512ab78aa..66ccd54ece7 100644 --- a/examples/internal/browser/a_bit_of_everything_service.spec.js +++ b/examples/internal/browser/a_bit_of_everything_service.spec.js @@ -7,7 +7,7 @@ describe('ABitOfEverythingService', function() { beforeEach(function(done) { new SwaggerClient({ - url: "http://localhost:8080/swagger/a_bit_of_everything.swagger.json", + url: "http://localhost:8080/openapiv2/a_bit_of_everything.swagger.json", usePromise: true, }).then(function(c) { client = c; diff --git a/examples/internal/browser/echo_service.spec.js b/examples/internal/browser/echo_service.spec.js index 97888c3e6c7..72aa13ca48e 100644 --- a/examples/internal/browser/echo_service.spec.js +++ b/examples/internal/browser/echo_service.spec.js @@ -7,7 +7,7 @@ describe('EchoService', function() { beforeEach(function(done) { new SwaggerClient({ - url: "http://localhost:8080/swagger/echo_service.swagger.json", + url: "http://localhost:8080/openapiv2/echo_service.swagger.json", usePromise: true, }).then(function(c) { client = c; diff --git a/examples/internal/browser/gulpfile.js b/examples/internal/browser/gulpfile.js index f1e03e5d9fa..f287428d80e 100644 --- a/examples/internal/browser/gulpfile.js +++ b/examples/internal/browser/gulpfile.js @@ -32,7 +32,7 @@ gulp.task('serve-server', ['server'], function () { gulp.task('serve-gateway', ['gateway', 'serve-server'], function () { gprocess.start('gateway-server', 'bin/example-gw', [ - '--logtostderr', '--swagger_dir', path.join(__dirname, "../proto/examplepb"), + '--logtostderr', '--openapi_dir', path.join(__dirname, "../proto/examplepb"), ]); gulp.watch('bin/example-gw', ['serve-gateway']); }); diff --git a/examples/internal/browser/index.html b/examples/internal/browser/index.html index 7817451ca82..da9e223e3bf 100644 --- a/examples/internal/browser/index.html +++ b/examples/internal/browser/index.html @@ -4,7 +4,7 @@