feat: add expand_slashed_path_patterns flag

[czabaj]

References to other Issues or PRs

Closes #4784 - a feature request

Have you read the Contributing Guidelines?

Yes 👍

Brief description of what is fixed or changed

This adds an experimental flag into the OpenAPI generator, that expands path patterns containing URI sub-paths into the URI with new path parameters. This improves the readability and OpenAPI compatibility of protobuf APIs based on Google AIP. For more context read the linked issue.

[johanbrandhorst]

This is a great start. Could you please make sure to also:

1. Add this new flag to the bazel rules for the openapiv2 generator. Just follow the pattern for the other flags.
2. Add a small section to our docs about this new flag with some example use cases? The file you want is https:/grpc-ecosystem/grpc-gateway/blob/main/docs/docs/mapping/customizing_openapi_output.md.

Thanks!

[czabaj]

I created a single clean function that patches the path parts & params only when the flag is turned on. It consumes the parts from the templateToParts function which I reverted to its original shape. While running the test, I encountered a bug in templateToParts, or at least, I think it is a bug.

If you pass into the templateToParts URI template with a path param pattern, that uses a snake-case URI, like

/test/{name=test_cases/*}/

where the path pattern contains snake-kase test_cases_ and the useJSONNamesForFields` is turned on, then this is split into parts

test
name=testCases/*

so the path pattern is camelcased. I believe this is wrong, since only the path parameter names should be camelcased, not other parts of the URI - am I right?

[johanbrandhorst]

I believe this is wrong, since only the path parameter names should be camelcased, not other parts of the URI - am I right?

Yeah this looks wrong, thanks for finding it. Can you fix it?

[johanbrandhorst]

I just realized that we have a package for parsing these paths already: https:/grpc-ecosystem/grpc-gateway/blob/main/internal/httprule. What do you think about reusing this?

[czabaj]

I tried that package but unfortunately, it doesn't fit as a replacement for the templateToParts function, I encountered these problems

• the templateToParts split the template by slashes, so a template with a leading slash creates an empty string at the start of the output slice, trailing slash in the template creates an empty string at the end of the slice - I can go around this, but httprule.Parse do not even accept templates without trailing slash, which broke some tests - I guess that all templates should generally be with trailing slash, but I'm not certain.
• the httprule.Parse ignores and omits the path patterns, these are completely lost in the Compile output object, this was a blocker,
• the Compile.Pool contains template segments, but the order is not guaranteed, I encountered a test with a path param where the order of the segments was different than in the original template, this is hard to resolve,

Overall, httprule.Parse does a lot of stuff, but most of it is not useful for the templateToParts, and the important stuff is missing and hard to add. At least, I managed to simplify the templateToParts and fix the camel-casing, which wrongly affected the parameter pattern.

[johanbrandhorst]

Thanks for the explanation, that makes sense!

[czabaj]

This second jsonBuffer was just a complexity gainer, I added a single branch to the } case, where it extracts the parameter name and camel-case it, when the camel-casing is enabled.

[johanbrandhorst]

This is really cool, as a final request, do you think you could add a little blurb about this setting to our docs? This page: https:/grpc-ecosystem/grpc-gateway/blob/main/docs/docs/mapping/customizing_openapi_output.md

[johanbrandhorst]

Looks like there was a test failure, I think it's from the camelcase fix you made.