Add custom options to allow more control of swagger/openapi output (#145

) Creates additional options that can be applied to RPCs and messages that provide additional information in the OpenAPIv2 spec. These new options allow for the inclusion of Swagger object information (maps to a .proto file): * `info` * `host` * `base_path` * `schemes` * `consumes` * `produces` * `external_docs` Service information: * `tags` * `summary` * `description` * `external_docs` * `operation_id` * `consumes` * `produces` * `schemes` Operation information (maps to a method): * `tags` * `summary` * `description` * `external_docs` * `operation_id` * `consumes` * `produces` * `schemes` Schema information (maps to a message): * `json_schema` * `descriptor` * `read_only` * `external_docs` * `example` Additionally: * Change from 'Swagger: ' to 'OpenAPI: ' prefix. It should also be relatively simple to add any field that is missing to the new OpenAPI proto objects.
grpc-ecosystem · Nov 3, 2017 · 8cc3a55 · 8cc3a55
1 parent b0be3cd
commit 8cc3a55
Show file tree

Hide file tree

Showing 22 changed files with 1,612 additions and 197 deletions.
diff --git a/Makefile b/Makefile
@@ -43,6 +43,9 @@ OUTPUT_DIR=_output
 RUNTIME_PROTO=runtime/internal/stream_chunk.proto
 RUNTIME_GO=$(RUNTIME_PROTO:.proto=.pb.go)
 
+OPENAPIV2_PROTO=protoc-gen-swagger/options/openapiv2.proto protoc-gen-swagger/options/annotations.proto
+OPENAPIV2_GO=$(OPENAPIV2_PROTO:.proto=.pb.go)
+
 PKGMAP=Mgoogle/protobuf/descriptor.proto=$(GO_PLUGIN_PKG)/descriptor,Mexamples/sub/message.proto=$(PKG)/examples/sub
 ADDITIONAL_FLAGS=
 ifneq "$(GATEWAY_PLUGIN_FLAGS)" ""
@@ -83,17 +86,20 @@ generate: $(RUNTIME_GO)
 
 .SUFFIXES: .go .proto
 
-$(GO_PLUGIN): 
+$(GO_PLUGIN):
 	go get $(GO_PLUGIN_PKG)
 	go build -o $@ $(GO_PLUGIN_PKG)
 
 $(RUNTIME_GO): $(RUNTIME_PROTO) $(GO_PLUGIN)
 	protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I. --go_out=$(PKGMAP):. $(RUNTIME_PROTO)
 
+$(OPENAPIV2_GO): $(OPENAPIV2_PROTO) $(GO_PLUGIN)
+	protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I. --go_out=$(PKGMAP):$(GOPATH)/src $(OPENAPIV2_PROTO)
+
 $(GATEWAY_PLUGIN): $(RUNTIME_GO) $(GATEWAY_PLUGIN_SRC)
 	go build -o $@ $(GATEWAY_PLUGIN_PKG)
 
-$(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC)
+$(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC) $(OPENAPIV2_GO)
 	go build -o $@ $(SWAGGER_PLUGIN_PKG)
 
 $(EXAMPLE_SVCSRCS): $(GO_PLUGIN) $(EXAMPLES)
@@ -143,5 +149,6 @@ realclean: distclean
 	rm -f $(GO_PLUGIN)
 	rm -f $(SWAGGER_PLUGIN)
 	rm -f $(EXAMPLE_CLIENT_SRCS)
+	rm -f $(OPENAPIV2_GO)
 
 .PHONY: generate examples test lint clean distclean realclean
diff --git a/examples/clients/abe/a_bit_of_everything_nested.go b/examples/clients/abe/a_bit_of_everything_nested.go
@@ -1,10 +1,10 @@
 /* 
- * examples/examplepb/a_bit_of_everything.proto
+ * A Bit of Everything
  *
  * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
  *
- * OpenAPI spec version: version not set
- * 
+ * OpenAPI spec version: 1.0
+ * Contact: none@example.com
  * Generated by: https://github.com/swagger-api/swagger-codegen.git
  */
 

diff --git a/examples/clients/abe/a_bit_of_everything_service_api.go b/examples/clients/abe/a_bit_of_everything_service_api.go
@@ -1,10 +1,10 @@
 /* 
- * examples/examplepb/a_bit_of_everything.proto
+ * A Bit of Everything
  *
  * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
  *
- * OpenAPI spec version: version not set
- * 
+ * OpenAPI spec version: 1.0
+ * Contact: none@example.com
  * Generated by: https://github.com/swagger-api/swagger-codegen.git
  */
 
@@ -91,7 +91,7 @@ func (a ABitOfEverythingServiceApi) Create(floatValue float32, doubleValue float
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -101,6 +101,7 @@ func (a ABitOfEverythingServiceApi) Create(floatValue float32, doubleValue float
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -150,7 +151,7 @@ func (a ABitOfEverythingServiceApi) CreateBody(body ExamplepbABitOfEverything) (
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -160,6 +161,7 @@ func (a ABitOfEverythingServiceApi) CreateBody(body ExamplepbABitOfEverything) (
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -213,7 +215,7 @@ func (a ABitOfEverythingServiceApi) DeepPathEcho(singleNestedName string, body E
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -223,6 +225,7 @@ func (a ABitOfEverythingServiceApi) DeepPathEcho(singleNestedName string, body E
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -275,7 +278,7 @@ func (a ABitOfEverythingServiceApi) Delete(uuid string) (*ProtobufEmpty, *APIRes
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -285,6 +288,7 @@ func (a ABitOfEverythingServiceApi) Delete(uuid string) (*ProtobufEmpty, *APIRes
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -311,7 +315,8 @@ func (a ABitOfEverythingServiceApi) Delete(uuid string) (*ProtobufEmpty, *APIRes
 }
 
 /**
- * 
+ * Echo allows posting a StringMessage value.
+ * It also exposes multiple bindings.  This makes it useful when validating that the OpenAPI v2 API description exposes documentation correctly on all paths defined as additional_bindings in the proto.
  *
  * @param value 
  * @return *SubStringMessage
@@ -335,7 +340,7 @@ func (a ABitOfEverythingServiceApi) Echo(value string) (*SubStringMessage, *APIR
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -345,6 +350,7 @@ func (a ABitOfEverythingServiceApi) Echo(value string) (*SubStringMessage, *APIR
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -371,14 +377,15 @@ func (a ABitOfEverythingServiceApi) Echo(value string) (*SubStringMessage, *APIR
 }
 
 /**
- * 
+ * Echo allows posting a StringMessage value.
+ * It also exposes multiple bindings.  This makes it useful when validating that the OpenAPI v2 API description exposes documentation correctly on all paths defined as additional_bindings in the proto.
  *
- * @param value 
+ * @param body 
  * @return *SubStringMessage
  */
-func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *APIResponse, error) {
+func (a ABitOfEverythingServiceApi) Echo2(body string) (*SubStringMessage, *APIResponse, error) {
 
-	var localVarHttpMethod = strings.ToUpper("Get")
+	var localVarHttpMethod = strings.ToUpper("Post")
 	// create path and map variables
 	localVarPath := a.Configuration.BasePath + "/v2/example/echo"
 
@@ -392,10 +399,9 @@ func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *AP
 	for key := range a.Configuration.DefaultHeader {
 		localVarHeaderParams[key] = a.Configuration.DefaultHeader[key]
 	}
-	localVarQueryParams.Add("value", a.Configuration.APIClient.ParameterToString(value, ""))
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -405,19 +411,22 @@ func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *AP
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
 	localVarHttpHeaderAccept := a.Configuration.APIClient.SelectHeaderAccept(localVarHttpHeaderAccepts)
 	if localVarHttpHeaderAccept != "" {
 		localVarHeaderParams["Accept"] = localVarHttpHeaderAccept
 	}
+	// body params
+	localVarPostBody = &body
 	var successPayload = new(SubStringMessage)
 	localVarHttpResponse, err := a.Configuration.APIClient.CallAPI(localVarPath, localVarHttpMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, localVarFileName, localVarFileBytes)
 
 	var localVarURL, _ = url.Parse(localVarPath)
 	localVarURL.RawQuery = localVarQueryParams.Encode()
-	var localVarAPIResponse = &APIResponse{Operation: "Echo_0", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
+	var localVarAPIResponse = &APIResponse{Operation: "Echo2", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
 	if localVarHttpResponse != nil {
 		localVarAPIResponse.Response = localVarHttpResponse.RawResponse
 		localVarAPIResponse.Payload = localVarHttpResponse.Body()
@@ -431,14 +440,15 @@ func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *AP
 }
 
 /**
- * 
+ * Echo allows posting a StringMessage value.
+ * It also exposes multiple bindings.  This makes it useful when validating that the OpenAPI v2 API description exposes documentation correctly on all paths defined as additional_bindings in the proto.
  *
- * @param body 
+ * @param value 
  * @return *SubStringMessage
  */
-func (a ABitOfEverythingServiceApi) Echo_2(body string) (*SubStringMessage, *APIResponse, error) {
+func (a ABitOfEverythingServiceApi) Echo3(value string) (*SubStringMessage, *APIResponse, error) {
 
-	var localVarHttpMethod = strings.ToUpper("Post")
+	var localVarHttpMethod = strings.ToUpper("Get")
 	// create path and map variables
 	localVarPath := a.Configuration.BasePath + "/v2/example/echo"
 
@@ -452,9 +462,10 @@ func (a ABitOfEverythingServiceApi) Echo_2(body string) (*SubStringMessage, *API
 	for key := range a.Configuration.DefaultHeader {
 		localVarHeaderParams[key] = a.Configuration.DefaultHeader[key]
 	}
+	localVarQueryParams.Add("value", a.Configuration.APIClient.ParameterToString(value, ""))
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -464,21 +475,20 @@ func (a ABitOfEverythingServiceApi) Echo_2(body string) (*SubStringMessage, *API
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
 	localVarHttpHeaderAccept := a.Configuration.APIClient.SelectHeaderAccept(localVarHttpHeaderAccepts)
 	if localVarHttpHeaderAccept != "" {
 		localVarHeaderParams["Accept"] = localVarHttpHeaderAccept
 	}
-	// body params
-	localVarPostBody = &body
 	var successPayload = new(SubStringMessage)
 	localVarHttpResponse, err := a.Configuration.APIClient.CallAPI(localVarPath, localVarHttpMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, localVarFileName, localVarFileBytes)
 
 	var localVarURL, _ = url.Parse(localVarPath)
 	localVarURL.RawQuery = localVarQueryParams.Encode()
-	var localVarAPIResponse = &APIResponse{Operation: "Echo_1", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
+	var localVarAPIResponse = &APIResponse{Operation: "Echo3", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
 	if localVarHttpResponse != nil {
 		localVarAPIResponse.Response = localVarHttpResponse.RawResponse
 		localVarAPIResponse.Payload = localVarHttpResponse.Body()
@@ -566,7 +576,7 @@ func (a ABitOfEverythingServiceApi) GetQuery(uuid string, singleNestedName strin
 
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -576,6 +586,7 @@ func (a ABitOfEverythingServiceApi) GetQuery(uuid string, singleNestedName strin
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -626,7 +637,7 @@ func (a ABitOfEverythingServiceApi) Lookup(uuid string) (*ExamplepbABitOfEveryth
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -636,6 +647,7 @@ func (a ABitOfEverythingServiceApi) Lookup(uuid string) (*ExamplepbABitOfEveryth
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -684,7 +696,7 @@ func (a ABitOfEverythingServiceApi) Timeout() (*ProtobufEmpty, *APIResponse, err
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -694,6 +706,7 @@ func (a ABitOfEverythingServiceApi) Timeout() (*ProtobufEmpty, *APIResponse, err
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header
@@ -745,7 +758,7 @@ func (a ABitOfEverythingServiceApi) Update(uuid string, body ExamplepbABitOfEver
 	}
 
 	// to determine the Content-Type header
-	localVarHttpContentTypes := []string{ "application/json",  }
+	localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime",  }
 
 	// set Content-Type header
 	localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -755,6 +768,7 @@ func (a ABitOfEverythingServiceApi) Update(uuid string, body ExamplepbABitOfEver
 	// to determine the Accept header
 	localVarHttpHeaderAccepts := []string{
 		"application/json",
+		"application/x-foo-mime",
 		}
 
 	// set Accept header

diff --git a/examples/clients/abe/api_client.go b/examples/clients/abe/api_client.go
@@ -1,10 +1,10 @@
 /* 
- * examples/examplepb/a_bit_of_everything.proto
+ * A Bit of Everything
  *
  * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
  *
- * OpenAPI spec version: version not set
- * 
+ * OpenAPI spec version: 1.0
+ * Contact: none@example.com
  * Generated by: https://github.com/swagger-api/swagger-codegen.git
  */
 

diff --git a/examples/clients/abe/api_response.go b/examples/clients/abe/api_response.go
@@ -1,10 +1,10 @@
 /* 
- * examples/examplepb/a_bit_of_everything.proto
+ * A Bit of Everything
  *
  * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
  *
- * OpenAPI spec version: version not set
- * 
+ * OpenAPI spec version: 1.0
+ * Contact: none@example.com
  * Generated by: https://github.com/swagger-api/swagger-codegen.git
  */
 

diff --git a/examples/clients/abe/configuration.go b/examples/clients/abe/configuration.go
@@ -1,10 +1,10 @@
 /* 
- * examples/examplepb/a_bit_of_everything.proto
+ * A Bit of Everything
  *
  * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
  *
- * OpenAPI spec version: version not set
- * 
+ * OpenAPI spec version: 1.0
+ * Contact: none@example.com
  * Generated by: https://github.com/swagger-api/swagger-codegen.git
  */
 

diff --git a/examples/clients/abe/examplepb_a_bit_of_everything.go b/examples/clients/abe/examplepb_a_bit_of_everything.go
@@ -1,10 +1,10 @@
 /* 
- * examples/examplepb/a_bit_of_everything.proto
+ * A Bit of Everything
  *
  * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
  *
- * OpenAPI spec version: version not set
- * 
+ * OpenAPI spec version: 1.0
+ * Contact: none@example.com
  * Generated by: https://github.com/swagger-api/swagger-codegen.git
  */