Add openapiv2_opt support for passing values to go templates via cli

[500poundbear]

References to other Issues or PRs

Fixes #3388

Have you read the Contributing Guidelines?

Yes

Brief description of what is fixed or changed

As proposed by @jgiles in #3388, this MR adds support for a new OpenAPI option that allows for Go template values to be interpolated.

For example, by specifying the following option: --openapiv2_opt go_template_args=my_key=my_value, my_value can then be passed to the Go templates generating the swagger comments. In this case, the go template can refer to the specific key here with {{ arg "my_key" }}.

Multiple go_template_args arguments can be specified.

Other comments

Summary by CodeRabbit

• New Features

  • Introduced the ability to use custom values in Go templates for generating proto file comments, enhancing documentation customization based on different environments.
  • Added a new flag goTemplateArgs to provide custom values that can override keys in Go templates, improving template flexibility.

• Documentation

  • Updated documentation with instructions on enabling use_go_templates and specifying custom values using go_template_args.
  • Added examples demonstrating the use of custom values within proto file comments.

• Bug Fixes

  • Implemented validation to ensure goTemplateArgs is used only when use_go_templates is enabled, preventing potential configuration errors.

[coderabbitai]

Walkthrough

The changes introduce the ability to pass custom key-value pairs via the command line and use them in Go templates within proto file comments. This feature enables dynamic content generation in OpenAPI documentation, such as varying external URLs based on the deployment environment.

Changes

File Path	Change Summary
docs/docs/mapping/customizing_openapi_output.md	Added documentation for using custom values in Go templates for proto file comments.
internal/descriptor/registry.go	Added goTemplateArgs field and methods to handle key-value pairs for Go templates.
protoc-gen-openapiv2/defs.bzl	Modified to handle go_template_args parameter and updated rule definition.
protoc-gen-openapiv2/internal/genopenapi/template.go	Added arg function to goTemplateComments for dynamic value retrieval.
protoc-gen-openapiv2/internal/genopenapi/template_test.go	Updated test functions to include goTemplateArgs parameter and logic.
protoc-gen-openapiv2/main.go	Added goTemplateArgs flag and validation logic for its use with use_go_templates.

Assessment against linked issues

Objective	Addressed	Explanation
Support passing key-value pairs on the command line and using them in comment Go templates (#3388).	✅

Poem

In the code where templates nest,
A rabbit hopped, fulfilling a quest.
With keys and values paired just right,
It crafted docs that shone so bright. 🌟🐇✨

---

Tips

Chat with CodeRabbit Bot (@coderabbitai)

• If you reply to a review comment from CodeRabbit, the bot will automatically respond.
• To engage with CodeRabbit bot directly around the specific lines of code in the PR, mention @coderabbitai in your review comment
• Note: Review comments are made on code diffs or files, not on the PR overview.
• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

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.

Note: For conversation with the bot, please use the review comments on code diffs or files.

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

[coderabbitai]

Review Status

Actionable comments generated: 7

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 46e828a and df18aef.

Files selected for processing (6)

• docs/docs/mapping/customizing_openapi_output.md (1 hunks)
• internal/descriptor/registry.go (2 hunks)
• protoc-gen-openapiv2/defs.bzl (4 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template.go (1 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template_test.go (10 hunks)
• protoc-gen-openapiv2/main.go (2 hunks)

Additional comments: 4

docs/docs/mapping/customizing_openapi_output.md (1)

• 234-291: The new section on using custom values in Go templates is clear and provides valuable information on how to enhance proto file comments with dynamic content.

internal/descriptor/registry.go (1)

• 603-604: The update to the SetIgnoreComments method correctly sets the ignoreComments field.

protoc-gen-openapiv2/defs.bzl (1)

• 320-323: The go_template_args attribute is correctly defined as a string_list to accept multiple key-value pairs for Go template interpolation.

protoc-gen-openapiv2/main.go (1)

• 136-147: The new functionality for goTemplateArgs and related error handling is correctly implemented and follows the existing code structure and style. The registry is being set up with the new and existing flags consistently.

[coderabbitai]

Review Status

Actionable comments generated: 0

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between df18aef and a0fb324.

Files selected for processing (1)

• docs/docs/mapping/customizing_openapi_output.md (1 hunks)

Additional comments: 1

docs/docs/mapping/customizing_openapi_output.md (1)

• 234-289: The new section on using custom values in Go templates is clear and provides useful examples for users to follow. The bash script and proto file examples demonstrate how to pass custom values to the templates effectively.

[johanbrandhorst]

This is an excellent PR, just a few doc suggestions, thanks!

[coderabbitai]

Review Status

Actionable comments generated: 7

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 85a43db and 4d7b9dc.

Files selected for processing (6)

• docs/docs/mapping/customizing_openapi_output.md (1 hunks)
• internal/descriptor/registry.go (2 hunks)
• protoc-gen-openapiv2/defs.bzl (4 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template.go (1 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template_test.go (10 hunks)
• protoc-gen-openapiv2/main.go (2 hunks)

Additional comments: 14

docs/docs/mapping/customizing_openapi_output.md (3)

• 234-246: The documentation clearly explains how to use custom values with Go templates, which is consistent with the summary and pull request details. The instructions are clear and provide the necessary steps to enable the feature and pass custom values.

• 257-265: The example script correctly demonstrates how to use the use_go_templates flag along with custom template values. It is a practical example that users can follow to understand how to apply the feature in their own scripts.

• 270-286: The example proto file provided in the documentation correctly showcases how to use custom values within the proto file comments. It includes the {{arg "environment_label"}} and {{arg "environment"}} placeholders, which will be replaced with the corresponding values passed in the script.

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

• 2486-2495: The implementation of the arg function within the goTemplateComments function is correct and follows the intended functionality of retrieving template arguments. The error message provided when an argument is not found is clear and should be helpful to users.

protoc-gen-openapiv2/internal/genopenapi/template_test.go (9)

• 5844-5844: The addition of goTemplateArgs to the struct is consistent with the summary stating that a new field was added to test cases.

• 5972-5983: The test case correctly demonstrates the use of goTemplateArgs in conjunction with useGoTemplate.

• 6007-6009: The logic to handle goTemplateArgs when useGoTemplate is true is correctly implemented.

• 6041-6041: The addition of goTemplateArgs to the struct is consistent with the summary stating that a new field was added to test cases.

• 6103-6134: The test case correctly demonstrates the use of goTemplateArgs in conjunction with useGoTemplate.

• 6222-6222: The logic to handle goTemplateArgs when useGoTemplate is true is correctly implemented.

• 6281-6281: The TestTagsWithGoTemplate function correctly sets goTemplateArgs as described in the summary.

• 6328-6331: The use of goTemplateArgs within the service tag description correctly demonstrates the intended functionality.

• 6353-6356: The expected output in the TestTagsWithGoTemplate function correctly reflects the use of goTemplateArgs.

protoc-gen-openapiv2/main.go (1)

• 136-147: The setup of the registry with the new and existing flags is correctly implemented.

[500poundbear]

I have updated with your suggested changes @johanbrandhorst. Thank you for the review

[johanbrandhorst]

LGTM

[johanbrandhorst]

Looks like there's a minor formatting issue with the bazel changes

[coderabbitai]

Review Status

Actionable comments generated: 4

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 305c0e5 and 2398f9b.

Files selected for processing (6)

• docs/docs/mapping/customizing_openapi_output.md (1 hunks)
• internal/descriptor/registry.go (2 hunks)
• protoc-gen-openapiv2/defs.bzl (4 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template.go (1 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template_test.go (10 hunks)
• protoc-gen-openapiv2/main.go (2 hunks)

Additional comments: 15

docs/docs/mapping/customizing_openapi_output.md (1)

• 234-288: The documentation for using custom values in Go templates is clear and provides useful examples for users to follow. It is consistent with the summary and pull request description, and it enhances the grpc-gateway's OpenAPI generation capabilities by allowing for more dynamic and environment-specific documentation.

internal/descriptor/registry.go (1)

• 598-600: The GetGoTemplateArgs method implementation is straightforward and does not introduce any issues.

protoc-gen-openapiv2/defs.bzl (3)

• 60-66: The addition of go_template_args parameter to the _run_proto_gen_openapi function aligns with the summary and pull request description.

• 236-242: The addition of go_template_args parameter to the _proto_gen_openapi_impl function aligns with the summary and pull request description.

• 320-325: The addition of go_template_args attribute to the protoc_gen_openapiv2 rule aligns with the summary and pull request description.

protoc-gen-openapiv2/internal/genopenapi/template_test.go (8)

• 5844-5844: The addition of goTemplateArgs to the test case struct is consistent with the summary and the pull request description, which indicates that test cases have been updated to support the new functionality.

• 6007-6009: The logic to set goTemplateArgs in the registry if they are provided in the test case is correct and aligns with the new feature implementation.

• 5973-5983: The test case correctly demonstrates the use of goTemplateArgs with the useGoTemplate option enabled, and the expected output is consistent with the functionality described in the pull request.

• 5986-5997: The test case for undefined goTemplateArgs is well-formed and checks for the correct behavior when a template argument is not found, which is in line with the new feature's error handling.

• 6222-6222: The use of SetGoTemplateArgs in the test setup is appropriate and ensures that the goTemplateArgs are set in the registry before running the test.

• 6281-6281: The SetGoTemplateArgs method is correctly used in the TestTagsWithGoTemplate function to set up the registry with the necessary template arguments for the test.

• 6329-6331: The test case correctly asserts the expected description output when using the arg template function with a defined key, which is consistent with the new feature's intended behavior.

• 6354-6355: The test case for the arg template function with a defined key is correctly asserting the expected output, which is "the my_value" in this case.

protoc-gen-openapiv2/main.go (2)

• 33-33: The addition of the goTemplateArgs flag is consistent with the summary and pull request description. It allows users to pass custom key-value pairs to Go templates.

• 139-141: The validation logic to ensure that go_template_args is only used when use_go_templates is enabled is correctly implemented.

[500poundbear]

@johanbrandhorst I've fixed the formatting issue in the bazel formatting. extra spaces

[johanbrandhorst]

😬. There's a command you can run in CONTRIBUTING.md that should get the formatting right for you.

[coderabbitai]

Review Status

Actionable comments generated: 4

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between bca0b83 and 71c6fdc.

Files selected for processing (6)

• docs/docs/mapping/customizing_openapi_output.md (1 hunks)
• internal/descriptor/registry.go (2 hunks)
• protoc-gen-openapiv2/defs.bzl (4 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template.go (1 hunks)
• protoc-gen-openapiv2/internal/genopenapi/template_test.go (10 hunks)
• protoc-gen-openapiv2/main.go (2 hunks)

Additional comments: 8

docs/docs/mapping/customizing_openapi_output.md (3)

• 234-246: The documentation clearly explains how to use the new go_template_args feature with examples. It is important to ensure that the provided examples are tested and work as expected to avoid any confusion for the users.

• 255-265: The example bash script correctly demonstrates how to use the use_go_templates flag along with the go_template_args option. It's important to ensure that the example is aligned with the actual implementation and that the keys used in the arg function within the Go templates match the keys provided in the command-line options.

• 270-286: The example proto file demonstrates the use of the arg function within Go templates to interpolate custom values. It is crucial to verify that the arg function is implemented as described and that it correctly retrieves the values from the goTemplateArgs based on the provided name.

internal/descriptor/registry.go (2)

• 78-86: The addition of the goTemplateArgs field to the Registry struct aligns with the PR objective to support command-line provided key-value pairs within Go templates.

• 598-600: The GetGoTemplateArgs method correctly provides access to the goTemplateArgs map.

protoc-gen-openapiv2/defs.bzl (2)

• 111-115: The implementation of go_template_args in the _run_proto_gen_openapi function correctly adds the provided key-value pairs to the args list, aligning with the PR objective and the summary.

• 111-115: Consider adding a validation check to ensure that go_template_args is only used when use_go_templates is set to true, as per the summary and pull request description.

protoc-gen-openapiv2/main.go (1)

• 30-36: The addition of the goTemplateArgs flag and the associated validation logic aligns with the PR objective and the summary of changes. The previous comments regarding the user-friendliness of the error message have been noted and should be considered.

[johanbrandhorst]

Thanks for your contribution!