Add collection format option to CLI tool documentation

[christianhelle]

This pull request introduces support for configurable collection formats for array query parameters in the Refitter tool. The changes include the addition of a new CollectionFormat enumeration, updates to the CLI and .refitter file format to accept this option, and corresponding updates to the documentation and tests.

Feature: Configurable Collection Format for Array Query Parameters

• Added CollectionFormat enumeration: Introduced a new CollectionFormat enum in src/Refitter.Core/Settings/CollectionFormat.cs to define supported formats such as Multi, Csv, Ssv, Tsv, and Pipes.
• Updated RefitGeneratorSettings: Added a CollectionFormat property in src/Refitter.Core/Settings/RefitGeneratorSettings.cs to allow configuration of the collection format for array query parameters, defaulting to Multi.
• Modified query attribute generation: Updated src/Refitter.Core/ParameterExtractor.cs to use the configured CollectionFormat when generating query attributes.

CLI and .refitter File Enhancements

• CLI support for --collection-format: Added a new --collection-format option to the CLI in src/Refitter/Settings.cs and updated examples in src/Refitter/Program.cs and README.md. [1] [2] [3] [4]
• .refitter file support: Extended the .refitter file format to include a collectionFormat property, with corresponding documentation updates in docs/docfx_project/articles/refitter-file-format.md. [1] [2]

Documentation Updates

• Documentation for CLI and .refitter updates: Updated docs/docfx_project/articles/cli-tool.md to document the new --collection-format option and its possible values. [1] [2]

Testing Enhancements

• New unit tests: Added comprehensive tests in src/Refitter.Tests/Examples/CollectionFormatTests.cs to validate the correct generation of code for different collection formats.
• Smoke tests: Updated test/smoke-tests.ps1 to include a test case for the --collection-format option with Csv as an example.

These changes ensure that users can flexibly configure how array query parameters are serialized, improving compatibility with different API specifications.

Summary by CodeRabbit

• New Features

  • Added support for configuring the format of collection (array) query parameters in the CLI tool and .refitter file, with options including Multi, Csv, Ssv, Tsv, and Pipes.
  • Introduced a new command-line option and configuration property to select the desired collection format for generated code.

• Documentation

  • Updated user guides and examples to document the new --collection-format option and its usage.
  • Enhanced .refitter file format documentation to include the new collectionFormat property.

• Tests

  • Added tests to verify correct code generation and compilation for each supported collection format.

[coderabbitai]

Walkthrough

The changes introduce a new configurable option, collectionFormat, for specifying how array query parameters are formatted in generated code. This is implemented as a new CollectionFormat enum with values such as Multi, Csv, Ssv, Tsv, and Pipes, and is surfaced through CLI, settings, and .refitter file support. Documentation and examples are updated to reflect the new option. The code generator and parameter extraction logic are modified to use the selected collection format. Tests and smoke tests are added to verify the correct handling and code generation for different collection formats.

Changes

Files/Paths	Change Summary
README.md, docs/docfx_project/articles/cli-tool.md, docs/docfx_project/articles/refitter-file-format.md	Updated documentation and examples to describe and demonstrate the new --collection-format option, its allowed values, and its usage in CLI and .refitter files.
src/Refitter.Core/Settings/CollectionFormat.cs	Added new CollectionFormat enum with values Multi, Csv, Ssv, Tsv, and Pipes, each documented with summaries and examples.
src/Refitter.Core/Settings/RefitGeneratorSettings.cs, src/Refitter/Settings.cs	Added new public property CollectionFormat to both RefitGeneratorSettings and Settings classes, with default value Multi, CLI binding, and documentation.
src/Refitter.Core/ParameterExtractor.cs	Modified query attribute generation logic to use the selected CollectionFormat from settings instead of the previously hardcoded Multi.
src/Refitter/GenerateCommand.cs	Passed the CollectionFormat property from CLI settings into generator settings during command execution.
src/Refitter/Program.cs	Added a new CLI usage example demonstrating the --collection-format Csv option.
src/Refitter.Tests/Examples/CollectionFormatTests.cs	Introduced new test class with tests verifying code generation, compilation, and correct attribute usage for different collection formats.
test/smoke-tests.ps1	Added a new smoke test scenario to generate and build code using the --collection-format csv option.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI/Settings
    participant CodeGenerator
    participant ParameterExtractor

    User->>CLI/Settings: Specify --collection-format (e.g., Csv)
    CLI/Settings->>CodeGenerator: Pass CollectionFormat setting
    CodeGenerator->>ParameterExtractor: Generate code for query parameters
    ParameterExtractor->>CodeGenerator: Use specified CollectionFormat in attributes
    CodeGenerator-->>User: Output code with correct collection format

Loading

Poem

🐇
A hop and a skip, a format anew,
Now arrays in queries can split right through!
Csv or Pipes, Ssv or Tabs,
Multi for many, the rabbit now grabs.
Tests and docs updated, the journey complete—
Collection formats make code extra neat!
🥕

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fb368ce and 59aff75.

📒 Files selected for processing (11)

• README.md (2 hunks)
• docs/docfx_project/articles/cli-tool.md (2 hunks)
• docs/docfx_project/articles/refitter-file-format.md (2 hunks)
• src/Refitter.Core/ParameterExtractor.cs (1 hunks)
• src/Refitter.Core/Settings/CollectionFormat.cs (1 hunks)
• src/Refitter.Core/Settings/RefitGeneratorSettings.cs (1 hunks)
• src/Refitter.Tests/Examples/CollectionFormatTests.cs (1 hunks)
• src/Refitter/GenerateCommand.cs (1 hunks)
• src/Refitter/Program.cs (1 hunks)
• src/Refitter/Settings.cs (1 hunks)
• test/smoke-tests.ps1 (1 hunks)

🧰 Additional context used

🧬 Code Graph Analysis (1)

src/Refitter.Tests/Examples/CollectionFormatTests.cs (2)

src/Refitter.Tests/Build/BuildHelper.cs (2)

• BuildHelper (6-53)
• BuildCSharp (8-45)

src/Refitter.Core/RefitGenerator.cs (1)

• RefitGenerator (10-300)

⏰ Context from checks skipped due to timeout of 90000ms (5)

• GitHub Check: Analyze (csharp)
• GitHub Check: 👌 Verify build
• GitHub Check: script
• GitHub Check: 👌 Verify build
• GitHub Check: 👌 Verify build

🔇 Additional comments (18)

src/Refitter/Program.cs (1)

159-163: Excellent addition of the --collection-format example.

The new example demonstrates how to use the --collection-format option with the "Csv" value, which is consistent with the existing example pattern and properly positioned after the polymorphic serialization example.

docs/docfx_project/articles/cli-tool.md (2)

42-42: Well-structured example for the new collection format option.

The example follows the established pattern and clearly demonstrates the --collection-format Csv usage.

---

86-91: Clear and comprehensive documentation for the collection format option.

The documentation effectively describes:

• Default value (Multi)
• All possible values with explanations
• Formatting consistent with other options in the documentation

This provides users with all necessary information to understand and use the new feature.

README.md (2)

63-63: Example correctly demonstrates the new collection format option.

The example follows the established pattern of other examples in the README and shows how to use the --collection-format Csv option.

---

107-107: Concise documentation of the collection format option for the README.

The description appropriately includes the default value (Multi) and available options in a format consistent with other options in the README. While less detailed than the CLI tool documentation, this is appropriate for the README context.

test/smoke-tests.ps1 (1)

182-182: Good test coverage for the new collection format option.

The test properly:

• Uses "CollectionFormatCsv" as the namespace suffix and output path prefix
• Includes the --collection-format csv argument
• Enables the .NET Core switch, consistent with similar feature tests
• Maintains the same pattern as other feature tests

This addition ensures the new feature is properly tested in smoke tests.

src/Refitter/GenerateCommand.cs (1)

149-149: Good work adding the CollectionFormat property to the RefitGeneratorSettings!

This change properly passes the collection format configuration from the CLI settings to the Refit generator settings, enabling configurable array query parameter formatting.

docs/docfx_project/articles/refitter-file-format.md (2)

66-66: Documentation updated correctly for the new CollectionFormat option.

The documentation clearly explains the purpose of the new collectionFormat property, its possible values, and its default value. This will help users understand how to configure array parameter formatting in their .refitter files.

---

425-425: Minor readability improvement to the withRequestOptions description.

Clean-up of trailing content in the description improves the documentation's consistency.

src/Refitter.Core/ParameterExtractor.cs (1)

119-120: Good implementation of the dynamic collection format.

The code now correctly uses the configured collection format from settings instead of hardcoding Multi. This enables users to choose their preferred format for array query parameters.

src/Refitter.Core/Settings/CollectionFormat.cs (1)

1-38: Well-structured enum with clear documentation.

The CollectionFormat enum is well-designed with appropriate XML documentation that clearly explains each format option and includes examples. This makes the code self-documenting and provides valuable information for developers working with the codebase.

The enum correctly implements the collection formats as defined in the Swagger 2.0 specification, providing a complete set of options for array parameter serialization.

src/Refitter.Core/Settings/RefitGeneratorSettings.cs (1)

366-372: Well-implemented property for collection format configuration.

The CollectionFormat property is properly implemented with comprehensive XML documentation, appropriate description attribute, and correct default value. The JSON serialization configuration ensures proper integration with configuration files.

src/Refitter/Settings.cs (1)

233-245: Excellent CLI integration for the collection format option.

The implementation includes a comprehensive description that clearly explains each format option with examples of how they appear in query strings. Linking to the Swagger documentation is particularly helpful for users who want to understand the feature in depth.

src/Refitter.Tests/Examples/CollectionFormatTests.cs (5)

9-62: Good test setup with comprehensive OpenAPI specification.

The test class is well-structured with a complete OpenAPI specification that includes both required and optional array parameters, providing a solid foundation for testing the collection format feature.

---

63-78: Basic generation and build tests verify functionality.

These tests ensure that the code can be generated with the collection format option and successfully builds, which is a good sanity check for the feature.

---

80-97: Comprehensive parameterized tests for all collection formats.

Excellent use of theory with inline data to test each supported collection format. The assertions properly verify that both required and optional parameters use the correct format attribute in the generated code.

---

99-125: Well-implemented helper method for code generation.

The GenerateCode method properly sets up the test environment, configures the settings with the specified collection format, and ensures proper cleanup of temporary files.

---

127-135: Clean file management in test helpers.

The CreateSwaggerFile method correctly handles temporary file creation with unique identifiers to avoid conflicts during parallel test execution.

✨ Finishing Touches

• 🔥 Error while generating docstrings. (🔄 Check again to generate docstrings again)

---

🪧 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>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• 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 testing code 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 gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

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 using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• 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/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull Request Overview

This PR adds configurable collection format support for array query parameters in the Refitter tool. The changes include introducing a new CollectionFormat enum and property, updating the CLI and generator settings to use this option, and enhancing tests and documentation to cover the new functionality.

• Added new CollectionFormat enum and corresponding properties in settings files.
• Updated CLI examples and Refit generator settings to propagate the new option.
• Enhanced tests and documentation to validate and describe the feature.

Reviewed Changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Refitter/Settings.cs	Added a new command-line option for specifying the collection format.
src/Refitter/Program.cs	Updated example configuration to include the --collection-format option.
src/Refitter/GenerateCommand.cs	Passed the CollectionFormat setting into the generator settings.
src/Refitter.Tests/Examples/CollectionFormatTests.cs	Added comprehensive tests to verify correct code generation for each collection format.
src/Refitter.Core/Settings/RefitGeneratorSettings.cs	Introduced a new property for CollectionFormat with proper JSON conversion.
src/Refitter.Core/Settings/CollectionFormat.cs	Defined the CollectionFormat enum with supported formats.
src/Refitter.Core/ParameterExtractor.cs	Updated the query attribute generation to use the configured collection format.
docs/docfx_project/articles/refitter-file-format.md	Extended .refitter file documentation to include the new collectionFormat property.
docs/docfx_project/articles/cli-tool.md	Documented the new --collection-format option with possible values.
README.md	Updated examples and option lists to reflect the new collection format support.

Files not reviewed (1)

• test/smoke-tests.ps1: Language not supported

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.51%. Comparing base (2ebf63f) to head (59aff75).
Report is 20 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #664      +/-   ##
==========================================
+ Coverage   95.47%   98.51%   +3.04%     
==========================================
  Files          59       60       +1     
  Lines        2896     2900       +4     
==========================================
+ Hits         2765     2857      +92     
+ Misses         99        4      -95     
- Partials       32       39       +7     

Flag	Coverage Δ
unittests	98.51% <100.00%> (+3.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Caution

An unexpected error occurred while opening a pull request: Not Found - https://docs.github.com/rest/git/refs#get-a-reference