Feature/issue 3051 swagger preserve rpc order

[CemGurhan]

References to other Issues or PRs

Fixes #3051

Have you read the Contributing Guidelines?

Yes

Brief description of what is fixed or changed

Currently, generated swagger files representing openapi definitions emit paths found in proto files in alphabetical order. This feature provides a new command line option called preserve_rpc_order. If set to true, once swagger files are generated, paths will maintain the order found in proto files. This should work for both json and yaml formats. Path ordering is also preserved in the following scenarios (as specified):

1. When using additional bindings, paths should preserve this ordering within an RPC
2. When using multiple services, paths should preserve the ordering between RPCs in the whole protobuf file
3. When merging protobuf files, paths should preserve the ordering specified on the command line.

Alphabetical ordering of paths was due to paths being keys to the openapiPathsObject map, stored inside the openapiSwaggerObject. Hence, upon encoding to JSON or YAML, paths were automatically ordered alphabetically. In order to resolve this issue, an ordered data structure was used instead for the openapiPathsObject.

Other comments

This is my first open source contribution, so do let me know if there's anything I can improve on!

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[johanbrandhorst]

Hi Cem, thanks a lot for taking this on. I think there's a fundamental problem with the change in that it doesn't output the correct swagger structure anymore. Instead of

 "paths": {
    "/v1/example/a_bit_of_everything": {
      "get": {

It's now doing

  "paths": [
    {
      "Path": "/v1/example/a_bit_of_everything",
      "PathItemObject": {
        "get": {

I think you'll need to go back to the structure and make sure it produces the correct format. Let me know if you need me to dig deeper.

[johanbrandhorst]

This is an excellent submission, sorry for the slow review!

[johanbrandhorst]

There are two warnings from golangci:

Error: func `isValidPathOrder` is unused (unused)
Error: S1001: should use copy(to, from) instead of a loop (gosimple)

Otherwise I think this is good to go!

[CemGurhan]

Thanks for the review Johan, let me know if there is anything more I can do/I've missed!

[johanbrandhorst]

Thanks a lot for the fixes Cem. I just remembered that we should add a section to the docs about this new functionality so users can find it easily. Would you mind adding something to https://github.com/grpc-ecosystem/grpc-gateway/blob/main/docs/docs/mapping/customizing_openapi_output.md to explain what this does and how to use it?

[CemGurhan]

Sure thing, will get on that now!

[johanbrandhorst]

Awesome, thank you!

[CemGurhan]

No problem, thanks for the reviews! Will hopefully be working on more issues for gRPC gateway soon : )

[eccles]

A big Thankyou to @CemGurhan and @johanbrandhorst for doing this. I have just implemented this in our system and it worked cleanly.
Thank you