From 5abbca7b18feb9ba6acd5fa05c80174a2e5da8f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=98yvind=20Matheson=20Wergeland?= Date: Fri, 20 May 2022 01:52:33 +0200 Subject: [PATCH] Document and warn about path parameters containing "/". (#2697) --- docs/docs/mapping/customizing_openapi_output.md | 5 +++++ protoc-gen-openapiv2/internal/genopenapi/template.go | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/docs/docs/mapping/customizing_openapi_output.md b/docs/docs/mapping/customizing_openapi_output.md index 4227f1eead6..baa5087f571 100644 --- a/docs/docs/mapping/customizing_openapi_output.md +++ b/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. diff --git a/protoc-gen-openapiv2/internal/genopenapi/template.go b/protoc-gen-openapiv2/internal/genopenapi/template.go index 21a9a8a5037..a6f0f4f4cab 100644 --- a/protoc-gen-openapiv2/internal/genopenapi/template.go +++ b/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)