Implement ordering for parameters

[kvaps]

Signed-off-by: Andrei Kvapil [email protected]

[gemini-code-assist]

Summary of Changes

Hello @kvaps, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the OpenAPI schema generation by introducing a mechanism to explicitly order parameters. By adding an Order field to the internal Node representation and implementing a custom sorting function, the system can now generate OpenAPI schemas where parameters appear in a predictable and desired sequence, improving the consistency and readability of the generated output.

Highlights

• Parameter Ordering: Introduced an Order field to the Node struct to explicitly store the sequence of parameters within the OpenAPI definition.
• Order Assignment: The Build function now assigns an incremental orderCounter to parameters as they are processed, ensuring a defined order.
• Custom Sorting Logic: Implemented a new sortedKeysByOrder function that sorts parameters primarily by their assigned Order value, falling back to lexicographical sorting for parameters with no explicit order.
• Schema Generation Update: Modified the schema generation process in writeStruct and WriteValuesSchema to utilize the new sortedKeysByOrder function, ensuring that generated OpenAPI schemas reflect the intended parameter order.
• New Schema Writer: Added WriteValuesSchemaWithOrder to allow for the generation of schemas with explicit parameter ordering, which is now called from main.go.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ordering

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces ordering for parameters, which is then used to generate an ordered values.schema.json. The implementation adds an Order field to the Node struct and populates it as parameters are parsed. My review identified a critical bug in the sorting logic that fails to correctly order parameters and a medium-severity issue with JSON formatting that results in misaligned output. I've provided code suggestions to address both of these issues.

[gemini-code-assist]

The sorting logic in sortedKeysByOrder is flawed and doesn't correctly order parameters.

1. The first parameter is assigned Order = 0, which is the same as the default for non-parameter fields. When comparing this parameter with a non-parameter, the if nodeI.Order != 0 || nodeJ.Order != 0 condition is false, causing it to fall back to alphabetical sorting. This is incorrect.
2. When comparing a parameter with Order > 0 against a non-parameter with Order = 0, the condition nodeI.Order < nodeJ.Order will be false, causing the non-parameter to be sorted first.

A more robust approach is to use the IsParam boolean field, which clearly distinguishes parameters from other fields. This ensures parameters are always sorted before non-parameters, and then by their specified order.

sort.Slice(keys, func(i, j int) bool {
			nodeI := nodes[keys[i]]
			nodeJ := nodes[keys[j]]
			if nodeI.IsParam && nodeJ.IsParam {
				return nodeI.Order < nodeJ.Order
			}
			if nodeI.IsParam {
				return true
			}
			if nodeJ.IsParam {
				return false
			}
			return keys[i] < keys[j]
		})

[gemini-code-assist]

The manual JSON generation for properties results in incorrect indentation in the output values.schema.json file. Using json.MarshalIndent with a hardcoded prefix for the property value causes misalignment because the prefix is applied to every line of the marshaled object, including the first one.

To produce a correctly formatted JSON, you can marshal the property without a prefix and then manually handle the indentation to align it properly under its key.

propJSON, err := json.MarshalIndent(prop, "", "  ")
						if err != nil {
							return err
						}

						// Manually indent the property JSON to align correctly.
						lines := strings.Split(string(propJSON), "\n")
						buf.WriteString(fmt.Sprintf("    \"%s\": %s", key, lines[0]))
						for _, line := range lines[1:] {
							buf.WriteString("\n    " + line)
						}