Skip to content

Commit 5abbca7

Browse files
authored
Document and warn about path parameters containing "/". (grpc-ecosystem#2697)
1 parent a03e328 commit 5abbca7

File tree

2 files changed

+10
-0
lines changed

2 files changed

+10
-0
lines changed

docs/docs/mapping/customizing_openapi_output.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -478,6 +478,11 @@ This will instead generate the following paths:
478478
- `/v1/{shelfName}`
479479
- `/v1/{bookName}`
480480

481+
Note that path parameters in OpenAPI does not support values with `/`, as discussed in
482+
[Support for path parameters which can contain slashes #892](https://github.com/OAI/OpenAPI-Specification/issues/892),
483+
so tools as Swagger UI will URL encode any `/` provided as parameter value. A possible workaround for this is to write
484+
a custom post processor for your OAS file to replace any path parameter with `/` into multiple parameters.
485+
481486
### Output format
482487

483488
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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -938,9 +938,14 @@ func partsToOpenAPIPath(parts []string, overrides map[string]string) string {
938938
// For example "{name=organizations/*/roles/*}" would produce the regular expression for the "name" parameter of
939939
// "organizations/[^/]+/roles/[^/]+" or "{bar=bing/*/bang/**}" would produce the regular expression for the "bar"
940940
// parameter of "bing/[^/]+/bang/.+".
941+
//
942+
// Note that OpenAPI does not actually support path parameters with "/", see https://github.com/OAI/OpenAPI-Specification/issues/892
941943
func partsToRegexpMap(parts []string) map[string]string {
942944
regExps := make(map[string]string)
943945
for _, part := range parts {
946+
if strings.Contains(part, "/") {
947+
glog.Warningf("Path parameter '%s' contains '/', which is not supported in OpenAPI", part)
948+
}
944949
if submatch := canRegexp.FindStringSubmatch(part); len(submatch) > 2 {
945950
if strings.HasPrefix(submatch[2], "=") { // this part matches the standard and should be made into a regular expression
946951
// 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)

0 commit comments

Comments
 (0)