fix(protoc-gen-openapiv2): exclude from query params oneof fields in the same group as the one used in the body

[ovargas]

References to other Issues or PRs

Fixes #3861

Have you read the Contributing Guidelines?

Brief description of what is fixed or changed

Exclude from OpenApi generated documentation parameters in the query string if a field from the same oneof group is set in the body

Other comments

Summary by CodeRabbit

• Tests

  • Introduced tests for RPC generation involving one-of fields and additional bindings to ensure robust functionality.

• New Features

  • Enhanced the handling of one-of fields in API requests to improve the API's flexibility and correctness.

• Bug Fixes

  • Fixed an issue where duplicate paths were generated, ensuring cleaner and more accurate API documentation.

[coderabbitai]

Walkthrough

The changes include the addition of a new test function to verify the generation of RPCs that include one-of fields with additional bindings, ensuring correct path generation without duplicates. Additionally, a new function has been added to determine if a field in a protobuf message is part of the same one-of group as the body, aiding in the correct generation of query parameters.

Changes

File Path	Changes
protoc-gen-openapiv2/internal/genopenapi/generator_test.go	- Added TestGenerateRPCOneOfFieldBodyAdditionalBindings function. - Modified loop in findExpectedPaths to avoid duplicates.
protoc-gen-openapiv2/internal/genopenapi/template.go	- Added isBodySameOneOf function to improve message to query parameter conversion.

Assessment against linked issues

Objective	Addressed	Explanation
Identify and resolve the issue where the openapi documentation includes the other fields in the same oneof group as query params.	✅
Ensure that for paths ***/foo, ***/bar, ***/baz, the query string reference does not include the other fields in the oneof as query params.	✅
Verify that the generated openapi documentation accurately reflects the usage of oneof fields in the body.	✅
Address the discrepancy between the behavior in the grpc gateway and the openapi documentation regarding the handling of oneof fields.	✅

🐇
To code we hop, with each commit a leap,
No duplicate paths, in our tests, we keep.
With one-of fields, we gracefully bound,
CodeRabbit's updates, in OpenAPI found. 🌟
🐾

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

---

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit-tests for this file.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit tests for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository from git and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit tests.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• The JSON schema for the configuration file is available here.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.v2.json

CodeRabbit Discord Community

Join our Discord Community to get help, request features, and share feedback.

[coderabbitai]

Review Status

Actionable comments generated: 0

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 20d2d62 and 3a63505.

Files selected for processing (2)

• protoc-gen-openapiv2/internal/genopenapi/generator_test.go (2 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template.go (2 hunks)

Additional comments: 4

protoc-gen-openapiv2/internal/genopenapi/generator_test.go (2)

• 1185-1286: The new test function TestGenerateRPCOneOfFieldBodyAdditionalBindings is designed to ensure that oneof fields used in the body of a request are not included as query parameters in the OpenAPI documentation. The test checks for the presence of expected paths and the absence of query parameters in the content. This aligns with the PR's objective to correct the behavior of the OpenAPI documentation generation process.

• 1796-1807: The modification to the findExpectedPaths function includes a new map seenPaths to track already found paths and prevent duplicates. This is a good improvement to ensure that the function's output is accurate and free of redundancies.

protoc-gen-openapiv2/internal/genopenapi/template.go (2)

• 167-177: The logic within messageToQueryParameters correctly skips fields that are not visible or are part of a oneof group that is used in the body. This aligns with the PR's objective to exclude from query params oneof fields in the same group as the one used in the body.

• 191-205: The isBodySameOneOf function correctly checks if the field is part of a oneof group and if it is the same group as the body field. The logic appears to be correct and should function as intended based on the PR's objectives.

[coderabbitai]

Review Status

Actionable comments generated: 0

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 20d2d62 and aa1640d.

Files ignored due to filter (2)

• examples/internal/clients/echo/api/swagger.yaml
• examples/internal/proto/examplepb/echo_service.swagger.json

Files selected for processing (3)

• examples/internal/clients/echo/api_echo_service.go (3 hunks)
• protoc-gen-openapiv2/internal/genopenapi/generator_test.go (2 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template.go (2 hunks)

Files skipped from review due to trivial changes (1)

• examples/internal/clients/echo/api_echo_service.go

Files skipped from review as they are similar to previous changes (2)

• protoc-gen-openapiv2/internal/genopenapi/generator_test.go
• protoc-gen-openapiv2/internal/genopenapi/template.go

[johanbrandhorst]

This is an excellent PR, thank you! Just one minor typo comment.

[coderabbitai]

Review Status

Actionable comments generated: 0

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between aa1640d and b8d5d29.

Files selected for processing (1)

• protoc-gen-openapiv2/internal/genopenapi/generator_test.go (2 hunks)

Additional comments: 2

protoc-gen-openapiv2/internal/genopenapi/generator_test.go (2)

• 1185-1285: The new test TestGenerateRPCOneOfFieldBodyAdditionalBindings is designed to check the correct generation of RPC documentation when a oneof field is used in the request body and additional bindings are present. It's important to ensure that the test covers all necessary cases and that the logic within the test is sound and follows best practices for testing in Go.

• The test uses table-driven tests for different formats (JSON and YAML), which is a good practice in Go.
• The test checks if the generated content contains the expected paths and does not contain any query parameters for oneof fields, which aligns with the PR's objective.
• The use of t.Parallel() is appropriate for concurrent execution of tests.

• 1799-1804: The function findExpectedPaths is used to avoid duplicates in the found paths. It's good to see that the function is designed to be reusable and is used across multiple tests. This promotes DRY principles and improves maintainability.

[johanbrandhorst]

LGTM

[johanbrandhorst]

Thank you for your contribution!