protoc-gen-openapiv2: numbering logic and 'pattern' field of path parameters do not provide sufficient information for the Swagger UI

[llsj14]

🐛 Bug Report

When I split a monolithic single service into multiple services and use them to generate a single swagger file, it seems that the numbering logic of path parameters(docs) is used and thepattern field is generated in path parameters. However, this format results in missing path information from the swagger UI as following picture. There is a lack of information that how I should describe the path with this Swagger UI result.

I cannot find it in the documentation, but I'm also wondering if I can turn off these numbering logic and pattern field options for path parameters. Thank you.

To Reproduce

Step 1. Split single service into multiple services Step 2. Generate the swagger file(swagger.json) with the merge option. (--openapiv2_opt allow_merge=true) -> numbering logic and pattern field option of path parameters will be turned on Step 3. Check generated swagger file and Swagger UI results

Expected behavior

a.swagger.json (generated swagger file by protoc-gen-openapiv2)

    "/v1/{name=users/*/wallet}": {
      "get": {
        "summary": "abcd",
          "default": {
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ]

Swagger UI result

Actual Behavior

a.swagger.json (generated swagger file by protoc-gen-openapiv2)

    "/v1alpha/{name}": {
      "get": {
        "summary": "abcd",
          "default": {
            }
          },
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "users/[^/]+/wallet"
          }
        ]

Swagger UI result

Your Environment

macOS go1.16.15 darwin/amd64 protoc-gen-grpc-gateway v2.11.2 protoc-gen-openapiv2 v2.11.2

[oyvindwe]

Hi @llsj14

You're not the only one struggling with this! This is the intended behaviour for several reasons

• / is not allowed as a character in a OpenAPI path parameter. This is discussed for future OpenAPI versions: https://github.com/OAI/OpenAPI-Specification/issues/892
• Keeping =<pattern> in paths is also not allowed in OpenAPI path parameters.
• Paths in OpenAPI must be unique, so the generator enumerates variable names that would otherwise result in duplicate paths.

I assume you also got warnings like Path parameter 'name' contains '/', which is not supported in OpenAPI?

Did you try use the the path_parameter_name annotation as described in the documentation?

This issue is thoroughly discussed in #720

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[llsj14]

Thank you @oyvindwe, I got a great help!