BED-6664: Updated open api description to reflect fallback functionality in endpoints

[specter-flq]

Description

Added new descriptiont text in yaml file for asset group tag id query param that is used in multiple endpoints. Also generated new open api doc file and included here with changes.

Note: It includes a change that I had added in a previous PR but forgot to generate the new file. Previous PR is and Ticket is BED-6548

Motivation and Context

Resolves: BED-6664

How Has This Been Tested?

Generating the new file and manually going to API explorer in BHE and BHCE to confirm new text is there.

Screenshots (optional):

Types of changes

• Chore (a change that does not modify the application functionality)

Checklist:

• I have met the contributing prerequisites
  • Assigned myself to this PR
  • Added the appropriate labels
  • Associated an issue: Issues and Pull Requests README #672
  • Read the Contributing guide: https://github.com/SpecterOps/BloodHound/wiki/Contributing
• I have ensured that related documentation is up-to-date
  • Open API docs
  • Code comments (GoDocs / JSDocs)
• I have followed proper test practices
  • Added/updated tests to cover my changes
  • All new and existing tests passed

Summary by CodeRabbit

• New Features

  • Added product_edition field to the API version response.

• Documentation

  • Clarified that the asset_group_tag_id parameter can be associated with both 'Tier Zero' and 'Hygiene' zones when not supplied.

[coderabbitai]

Walkthrough

Updates to the OpenAPI schema documentation add a new product_edition field to the version endpoint response and modify the description of the asset_group_tag_id query parameter to reference both 'Tier Zero' and 'Hygiene' zones instead of only 'Tier Zero'.

Changes

Cohort / File(s)	Change Summary
OpenAPI Schema Updates packages/go/openapi/doc/openapi.json, packages/go/openapi/src/parameters/query.asset-group-tag-id.yaml	Added product_edition field to the version API response schema; updated asset_group_tag_id parameter description to reference both 'Tier Zero' and 'Hygiene' zones when not supplied

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Minor documentation updates to OpenAPI schema with straightforward description changes
• Ensure consistency between the generated OpenAPI JSON and the source YAML parameter definition

Possibly related PRs

• BE-6548: Added product edition to VersionResponse #2006: Adds the same product_edition field to the version API response alongside the schema updates in this PR.
• bed-6237: update documentation for posture endpoint #1724: Modifies the asset_group_tag_id query parameter definition; this PR updates the shared parameter description while the related PR adjusts its inline reference.

Suggested labels

documentation

Suggested reviewers

• wes-mil
• mistahj67

Poem

🐰 A new field hops into view,
Product_edition, fresh and true,
Hygiene joins Tier Zero's side,
In schema docs, side by side! 🌿

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "BED-6664: Updated open api description to reflect fallback functionality in endpoints" directly describes a real and significant part of the changeset. It accurately reflects the primary objective stated in the PR description: updating the asset_group_tag_id parameter description to reflect the fallback behavior for both 'Tier Zero' and 'Hygiene' zones. The title is specific, concise, and includes the ticket identifier, making it clear and scannable for someone reviewing the commit history. While the changeset also includes a new product_edition field added during OpenAPI file regeneration, the title focuses on the main described work of updating documentation text.
Description Check	✅ Passed	The pull request description follows the required template structure with all major sections present: Description, Motivation and Context (with Jira ticket reference BED-6664), How Has This Been Tested, Screenshots, Types of changes, and a completed Checklist. The author clearly identifies this as a chore that updates OpenAPI documentation and provides evidence through a screenshot. However, the description contains minor issues including a typo ("descriptiont"), incomplete text in the historical context section, and the testing section is relatively brief despite including photographic evidence. These issues are non-critical and do not prevent understanding the purpose and scope of the changes.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch BED-6664--asset-grp-tg-id-openapi

---

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.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

packages/go/openapi/doc/openapi.json (2)

3366-3370: Document allowed values for product_edition and add a brief description.

Great addition. To make clients stricter and self-describing, suggest enumerating editions and adding a description (and optionally a minimal example):

                         "server_version": {
-                          "type": "string"
+                          "type": "string",
+                          "description": "Semantic version of the running BloodHound server (e.g., 2.30.1)."
                         },
                         "product_edition": {
-                          "type": "string"
+                          "type": "string",
+                          "description": "Product edition of this instance.",
+                          "enum": ["Community", "Enterprise"]
                         }

Optionally add a small 200-response example with both fields to help SDK generators.

Please confirm these enum values match what the server actually returns in both BHCE and BHE.

---

17398-17403: Clarify fallback semantics for asset_group_tag_id.

The new text is helpful. To avoid ambiguity for clients, explicitly state whether omission selects the union of both zones or a precedence rule, and whether this fallback is environment-scoped.

Proposed tweak:

- "description": "The asset group tag id of the zone requested. If not supplied, the asset group tag id associated with 'Tier Zero' and 'Hygiene' is used.",
+ "description": "Zone tag to scope results. If omitted, results are evaluated against both the 'Tier Zero' and 'Hygiene' zones (union of both), within the current environment.",

If precedence or filtering differs, spell it out here since this parameter is reused across endpoints.

Please confirm whether the fallback behavior is union-of-both, first-match, or implementation-defined, and update the description accordingly.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bba455c and 8fac019.

📒 Files selected for processing (2)

• packages/go/openapi/doc/openapi.json (2 hunks)
• packages/go/openapi/src/parameters/query.asset-group-tag-id.yaml (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Build BloodHound Container Image / Build and Package Container
• GitHub Check: run-tests
• GitHub Check: build-ui
• GitHub Check: run-tests
• GitHub Check: run-analysis

🔇 Additional comments (1)

packages/go/openapi/src/parameters/query.asset-group-tag-id.yaml (1)

17-17: Clear documentation of fallback behavior.

The updated description effectively communicates the parameter's optional nature and its fallback behavior, now correctly specifying that both 'Tier Zero' and 'Hygiene' zones are included when the parameter is not supplied.