feat(RHINENG-21887): Add OpenAPI spec for /hosts-view endpoint

[adarshdubey-star]

JIra -: RHINENG-21887

Add complete OpenAPI 3.0 spec for the new /hosts-view endpoint that provides
a unified view of host data combined with application-specific metrics.

Summary by Sourcery

Add OpenAPI documentation for a new /hosts-view endpoint that returns an aggregated view of hosts with optional application metrics and supports rich filtering and sorting.

New Features:

• Define the /hosts-view GET endpoint in the OpenAPI spec for retrieving combined host and application data.
• Introduce query parameters for selecting application fields, filtering on application metrics, and ordering host views by host or application attributes.
• Add schemas describing host view responses, application-specific data structures, sparse field selection, and typed application-level filters.

[sourcery-ai]

Reviewer's Guide

Adds a complete OpenAPI 3.0 specification for the new /hosts-view endpoint, including its query parameters, ordering/filtering options, response schema, and supporting component schemas for application-specific host metrics.

Sequence diagram for GET /hosts-view request flow

sequenceDiagram
    actor ApiClient
    participant InventoryAPI as InventoryAPI_service

    ApiClient->>InventoryAPI: GET /hosts-view
    activate InventoryAPI
    InventoryAPI-->>InventoryAPI: Validate ApiKeyAuth
    InventoryAPI-->>InventoryAPI: Parse query params
    Note over InventoryAPI: displayName, fqdn, tagsParam, hostViewFieldsParam, hostViewAppFilterParam, hostViewOrderByParam, hostOrderHowParam, stalenessParam, pagination, etc.

    InventoryAPI-->>InventoryAPI: Build host query
    InventoryAPI-->>InventoryAPI: Apply app filters (HostViewApplicationFilter)
    InventoryAPI-->>InventoryAPI: Apply ordering (hostViewOrderByParam)
    InventoryAPI-->>InventoryAPI: Execute host and app joins

    InventoryAPI-->>ApiClient: 200 HostViewQueryOutput (paginated HostViewHost[])
    deactivate InventoryAPI

    alt Invalid query or parameters
        InventoryAPI-->>ApiClient: 400 Invalid request
    end

Loading

Entity relationship diagram for host view response model

erDiagram
    HostViewQueryOutput {
        string page
        string per_page
        string total
        HostViewHost[] results
    }

    HostViewHost {
        string id
        string display_name
        string fqdn
        string group_name
        string updated
        string last_check_in
        string system_profile
        HostApplicationsData app_data
    }

    HostApplicationsData {
        AdvisorAppData advisor
        VulnerabilityAppData vulnerability
        PatchAppData patch
        RemediationsAppData remediations
        ComplianceAppData compliance
        MalwareAppData malware
        ImageBuilderAppData image_builder
    }

    AdvisorAppData {
        int recommendations
        int incidents
    }

    VulnerabilityAppData {
        int total_cves
        int critical_cves
        int high_severity_cves
        int cves_with_security_rules
        int cves_with_known_exploits
    }

    PatchAppData {
        int installable_advisories
        string template
        string rhsm_locked_version
    }

    RemediationsAppData {
        int remediations_plans
    }

    ComplianceAppData {
        int policies
        datetime last_scan
    }

    MalwareAppData {
        string last_status
        int last_matches
        datetime last_scan
    }

    ImageBuilderAppData {
        string image_name
        string image_status
    }

    HostViewQueryOutput ||--o{ HostViewHost : contains
    HostViewHost ||--|| HostApplicationsData : has
    HostApplicationsData ||--o| AdvisorAppData : advisor
    HostApplicationsData ||--o| VulnerabilityAppData : vulnerability
    HostApplicationsData ||--o| PatchAppData : patch
    HostApplicationsData ||--o| RemediationsAppData : remediations
    HostApplicationsData ||--o| ComplianceAppData : compliance
    HostApplicationsData ||--o| MalwareAppData : malware
    HostApplicationsData ||--o| ImageBuilderAppData : image_builder

Loading

Class diagram for new /hosts-view schemas and parameters

classDiagram
    class HostViewQueryOutput {
        <<schema>>
        +int page
        +int per_page
        +int total
        +HostViewHost[] results
    }

    class HostViewHost {
        <<schema>>
        +string id
        +string display_name
        +string fqdn
        +string group_name
        +string updated
        +string last_check_in
        +object system_profile
        +HostApplicationsData app_data
    }

    class HostApplicationsData {
        <<schema>>
        +AdvisorAppData advisor
        +VulnerabilityAppData vulnerability
        +PatchAppData patch
        +RemediationsAppData remediations
        +ComplianceAppData compliance
        +MalwareAppData malware
        +ImageBuilderAppData image_builder
    }

    class AdvisorAppData {
        <<schema>>
        +int recommendations
        +int incidents
    }

    class VulnerabilityAppData {
        <<schema>>
        +int total_cves
        +int critical_cves
        +int high_severity_cves
        +int cves_with_security_rules
        +int cves_with_known_exploits
    }

    class PatchAppData {
        <<schema>>
        +int installable_advisories
        +string template
        +string rhsm_locked_version
    }

    class RemediationsAppData {
        <<schema>>
        +int remediations_plans
    }

    class ComplianceAppData {
        <<schema>>
        +int policies
        +datetime last_scan
    }

    class MalwareAppData {
        <<schema>>
        +string last_status
        +int last_matches
        +datetime last_scan
    }

    class ImageBuilderAppData {
        <<schema>>
        +string image_name
        +string image_status
    }

    class HostViewFieldsObject {
        <<schema>>
        +bool app_data
        +string[] advisor
        +string[] vulnerability
        +string[] patch
        +string[] remediations
        +string[] compliance
        +string[] malware
        +string[] image_builder
    }

    class HostViewApplicationFilter {
        <<schema>>
        +map<string,HostViewApplicationFilterField> applications
    }

    class HostViewApplicationFilterField {
        <<schema>>
        +map<string,HostViewFilterComparison> fields
    }

    class HostViewFilterComparison {
        <<schema>>
        +string eq
        +string ne
        +string gte
        +string lte
    }

    class hostViewFieldsParam {
        <<query_param>>
        +string name
        +string in
        +HostViewFieldsObject schema
    }

    class hostViewAppFilterParam {
        <<query_param>>
        +string name
        +string in
        +HostViewApplicationFilter schema
    }

    class hostViewOrderByParam {
        <<query_param>>
        +string name
        +string in
        +string enum_display_name
        +string enum_group_name
        +string enum_updated
        +string enum_operating_system
        +string enum_last_check_in
        +string enum_advisor_recommendations
        +string enum_vulnerability_total_cves
        +string enum_vulnerability_critical_cves
        +string enum_patch_installable_advisories
        +string enum_remediations_remediations_plans
        +string enum_compliance_policies
        +string enum_compliance_last_scan
        +string enum_malware_last_matches
        +string enum_malware_last_scan
    }

    HostViewQueryOutput --> HostViewHost : results
    HostViewHost --> HostApplicationsData : app_data
    HostApplicationsData --> AdvisorAppData
    HostApplicationsData --> VulnerabilityAppData
    HostApplicationsData --> PatchAppData
    HostApplicationsData --> RemediationsAppData
    HostApplicationsData --> ComplianceAppData
    HostApplicationsData --> MalwareAppData
    HostApplicationsData --> ImageBuilderAppData

    HostViewFieldsObject <.. hostViewFieldsParam : schema
    HostViewApplicationFilter <.. hostViewAppFilterParam : schema
    HostViewApplicationFilterField --> HostViewFilterComparison : comparisons
    HostViewApplicationFilter --> HostViewApplicationFilterField : fields_per_app

Loading

File-Level Changes

Change	Details	Files
Define the /hosts-view GET endpoint with security, filtering, pagination, and application join controls.	Add /hosts-view path with GET operationId api.host_views.get_host_views, hosts tag, summary, description, and ApiKeyAuth security. Reference existing host filtering, pagination, ordering, staleness, tags, registration, system type, and group parameters for the new endpoint. Introduce hostViewOrderByParam, hostViewAppFilterParam, and hostViewFieldsParam query components to support application-aware ordering, filtering, and sparse field selection.	swagger/api.spec.yaml swagger/openapi.json
Introduce response and host-level schemas that model combined host and application data.	Add HostViewQueryOutput schema extending PaginationOut with a results array of HostViewHost objects. Add HostViewHost schema extending HostOut and including an app_data field referencing HostApplicationsData. Define HostApplicationsData with references to per-application data objects (Advisor, Vulnerability, Patch, Remediations, Compliance, Malware, ImageBuilder).	swagger/api.spec.yaml swagger/openapi.json
Define per-application metrics objects and supporting field/filter configuration schemas for host views.	Add AdvisorAppData, VulnerabilityAppData, PatchAppData, RemediationsAppData, ComplianceAppData, MalwareAppData, and ImageBuilderAppData schemas with typed metric fields and validation constraints. Add HostViewFieldsObject schema and related enums to express sparse fieldsets for each application within the fields query param. Add HostViewApplicationFilter, HostViewApplicationFilterField, and HostViewFilterComparison schemas to formalize the filter[app][field][operator]=value deepObject query structure.	swagger/api.spec.yaml swagger/openapi.json

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey there - I've reviewed your changes - here's some feedback:

• The HostViewApplicationFilter schema currently allows arbitrary app_name and field keys via additionalProperties, while order_by and HostApplicationsData/HostViewFieldsObject enumerate a concrete set of apps and fields; consider tightening or documenting the allowed app/field combinations so clients get clearer validation/feedback when they send unsupported filter keys.
• The HostViewFilterComparison schema types all operator values as string, even for clearly numeric metrics (e.g., critical_cves, installable_advisories); if the backend expects numbers, it may be worth using a numeric type here to give clients better contract guarantees.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `HostViewApplicationFilter` schema currently allows arbitrary `app_name` and field keys via `additionalProperties`, while `order_by` and `HostApplicationsData`/`HostViewFieldsObject` enumerate a concrete set of apps and fields; consider tightening or documenting the allowed app/field combinations so clients get clearer validation/feedback when they send unsupported filter keys.
- The `HostViewFilterComparison` schema types all operator values as `string`, even for clearly numeric metrics (e.g., `critical_cves`, `installable_advisories`); if the backend expects numbers, it may be worth using a numeric type here to give clients better contract guarantees.

## Individual Comments

### Comment 1
<location> `swagger/api.spec.yaml:1387-1396` </location>
<code_context>
+    hostViewOrderByParam:
</code_context>

<issue_to_address>
**issue:** The `order_by` description and enum look misaligned with the supported fields.

The `hostViewOrderByParam` description claims it accepts any host column or `app:field`, but the schema limits it to a small enum that excludes several existing metrics (e.g. `vulnerability:high_severity_cves`, `vulnerability:cves_with_security_rules`, `vulnerability:cves_with_known_exploits` from `VulnerabilityAppData`). Please either expand the enum to include all sortable fields or update the description to match the allowed values, so the API contract is clear for consumers and tooling.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[jpramos123]

Thanks for the PR!

Please review and address below comments

[kruai]

I agree with Joao's comments; I also had a question about supported comparators.

[fstavela]

Please add a note to the description of the new endpoint that it's not implemented yet.

[ezr-ondrej]

This is great first version, I'm ok to go ahead with this as is if we make sure to include the prefix to ensure users don't get confused (description is not enough IMO).

I've floted a thought about having the app specific fields defined in separate file, but that can easily be a follow-up 👍

[thearifismail]

@adarshdubey-star I got one question about what should be the endpoint? Here is a link to Google Doc, which is pretty much a todo check list: https://docs.google.com/document/d/1jaDzGP1bXzvAzGzn1RIhy9TIPp4KWgzhEGhdg2yMbqA/

[adarshdubey-star]

/retest

[jpramos123]

This LGTM now!

If pipeline passes, feel free to merge.

[adarshdubey-star]

/retest