Document and warn about path parameters containing "/". (#2697)

docs/docs/mapping/customizing_openapi_output.md

@@ -478,6 +478,11 @@ This will instead generate the following paths:
 - `/v1/{shelfName}`
 - `/v1/{bookName}`
 
+Note that path parameters in OpenAPI does not support values with `/`, as discussed in
+[Support for path parameters which can contain slashes #892](https://github.com/OAI/OpenAPI-Specification/issues/892),
+so tools as Swagger UI will URL encode any `/` provided as parameter value. A possible workaround for this is to write
+a custom post processor for your OAS file to replace any path parameter with `/` into multiple parameters.
+
 ### Output format
 
 By default the output format is JSON, but it is possible to configure it using the `output_format` option. Allowed values are: `json`, `yaml`. The output format will also change the extension of the output files.

protoc-gen-openapiv2/internal/genopenapi/template.go

@@ -938,9 +938,14 @@ func partsToOpenAPIPath(parts []string, overrides map[string]string) string {
 // For example "{name=organizations/*/roles/*}" would produce the regular expression for the "name" parameter of
 // "organizations/[^/]+/roles/[^/]+" or "{bar=bing/*/bang/**}" would produce the regular expression for the "bar"
 // parameter of "bing/[^/]+/bang/.+".
+//
+// Note that OpenAPI does not actually support path parameters with "/", see https://github.com/OAI/OpenAPI-Specification/issues/892
 func partsToRegexpMap(parts []string) map[string]string {
 	regExps := make(map[string]string)
 	for _, part := range parts {
+		if strings.Contains(part, "/") {
+			glog.Warningf("Path parameter '%s' contains '/', which is not supported in OpenAPI", part)
+		}
 		if submatch := canRegexp.FindStringSubmatch(part); len(submatch) > 2 {
 			if strings.HasPrefix(submatch[2], "=") { // this part matches the standard and should be made into a regular expression
 				// assume the string's characters other than "**" and "*" are literals (not necessarily a good assumption 100% of the times, but it will support most use cases)