Openapi generator - explode the AIP style path parameters into URL with multiple path parameters

[czabaj]

🚀 Feature

We are building our API according to Google AIP, so our URL's contains typically just one path parameter, either {name} or {parent} which contains multiple URI segments, some of them dynamic, described via pattern, e.g.

service DocumentService {
  rpc ExportResults(ExportResultsRequest) returns (ExportResultsResponse) {
    option (google.api.http) = {
      post: "/v1/{name=projects/*/documents/*}:exportResults"
      body: "*"
    };
}

where the URI have just name parameter, but this one hides unnamed projectId and documentId parameters inside. This generates.

{
 "/v1/{name}:exportResults": {
      "post": {
        "operationId": "DocumentService_ExportResults",
        "responses": {
          "200": {
            "schema": {
              "$ref": "#/definitions/v1ExportResultsResponse"
            }
          },
          "default": {
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "projects/[^/]+/documents/[^/]+"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/DocumentServiceExportResultsBody"
            }
          }
        ]
      }
    }
}

You see, the URL of the resource "/v1/{name}:exportResults" is blurry for a documentation purpose. The fact, that the parameter name contains more dynamic URI segments is described in the parameters pattern, but again, not super readable.

This also causes a problem with OAS tooling, as path parameters in OpenAPI generally don't allow (unescaped) forward slashes, so many tools in OpenAPI space, that conform to OpenAPI spec, don't support parameters like that.

The problem with this is mentioned in the Documentation > Customizing openapi output > path parameters, where it states

Note that path parameters in OpenAPI does not support values with /, as discussed in Support for path parameters which can contain slashes #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.

I was thinking briefly about building the post-processor, but it seems to me like a good candidate for a built-in feature, since all people following Google AIP style have the same problem and will most probably end up with the same post-processor design, so why don't provide this feature in the generator? Or do you know any open-source post-processor available?

[johanbrandhorst]

If we could make this work, it would be great. It would have to be an option to avoid breaking users, but something like expand_slashed_path_parameters sounds reasonable. You'd have to parse the path parameter and expand it somehow. Feel free to open a PR if you can figure it out :).