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://github.com/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?

[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://github.com/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.

[johanbrandhorst]

Thank you for your contribution!