all: rename protoc-gen-swagger to protoc-gen-openapiv2

Fixes #675

.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!

.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:

BUILD

@@ -21,6 +21,6 @@ package_group(
     name = "generators",
     packages = [
         "//protoc-gen-grpc-gateway/...",
-        "//protoc-gen-swagger/...",
+        "//protoc-gen-openapiv2/...",
     ],
 )

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,23 +38,23 @@ 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=
 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)

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.
 

bin/.gitignore

@@ -1,3 +1,3 @@
 /protoc-gen-go
 /protoc-gen-grpc-gateway
-/protoc-gen-swagger
+/protoc-gen-openapiv2

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:
 

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

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
 

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.

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.
 

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).

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`.

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

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;