DI‐Portal‐PKGVER‐019 API Quality Validation Result

Design Item ID: DI-Portal-PKGVER-019
Design Item Name: API Quality Validation Result
Related Design Items:

• Ruleset Management for API Quality Check

Related API:

• Get validation summary for a package version (GET /api/v1/packages/{packageId}/versions/{version}/validation/summary)
• Get validated documents for a package version (GET /api/v1/packages/{packageId}/versions/{version}/validation/documents)
• Get validation result details for a specific document (GET /api/v1/packages/{packageId}/versions/{version}/validation/documents/{fileId}/details)

Revision History:

Date	Description
21.05.2025	Initial version for https://github.com/Netcracker/qubership-apihub/issues/120 / https://github.com/Netcracker/qubership-apihub/issues/119

---

Description

This functionality provides users with the ability to view the results of API quality validation (Spectral-based) for each published API version. Results are visualized through summary dashboards and detailed violation views. Validation is performed automatically upon publishing or republishing an package version, and the results are shown in the Summary and API Quality tabs.

Start Point

1. User navigates to APIHUB Portal → specific workspace→ specific group→ specific package version → Summary tab
2. User navigates to APIHUB Portal → specific workspace→ specific group→ specific package version → API Quality tab

Execution

Precondition: qubership-api-linter-service must be enabled.

The system verifies whether the qubership-api-linter-service is enabled:

1. API to check of linter service is enabled - GET /system/info
   • The API response includes the linterEnabled flag inside the SystemInfo object.
2. If the service is disabled, the API Quality tab and Quality Validation section in the Summary tab is not displayed in the UI and validation functionality is disabled for the user.

To view validation summary:

1. User clicks [Summary] tab.
   • API: GET /api/v1/packages/{packageId}/versions/{versionId}/validation/summary
2. The system displays the "Quality Validation" section under the "REST API Validation" with the following information:
   • If API quality check results are available:
     • Validation ruleset: Name of the ruleset used for validation and its status (e.g., ()).
     • Number of quality issues: Number of issues of each type - Errors, Warnings, and Info messages.
   • If package version does not have validation result:
     • The system displays the following static message under Quality Validation: "No validation results. Republish the version to start quality validation for the new revision.".
   • If linter service is still processing validation:
     • The system displays the following message: "Validation is in progress, please wait...".
   • API: GET /api/v1/packages/{packageId}/versions/{versionId}/validation/summary
3. User clicks the validation ruleset name:
   • The system opens a popup window with the following information about the selected ruleset:
     • Full name of the ruleset, combining its name and status (e.g., Ruleset ()).
     • Download link: A clickable link that allows the user to download the YAML file of the ruleset.
     • Activation history: A list of activation periods for the ruleset, displayed as date ranges.
     • API: GET /api/v1/rulesets/{id}

To view validation results:

1. User clicks on the [API Quality] tab.
   • If the validation status is inProgress or noResults, the [API Quality] tab is disabled. A tooltip is shown when hovering over the disabled tab with the message: "Validation results are not yet available. Please wait until validation is complete or republish the version."
2. The system automatically selects and displays the first document from the current package version and shows its validation results.
   • API: GET /api/v1/packages/{packageId}/versions/{versionId}/validation/documents
3. User selects a different document from the dropdown list to view its validation results.
   • Note: The document dropdown includes a search field that allows users to search documents by name. This search is fully handled on the frontend; the backend always returns the full list of documents in the response.
   • API: GET /api/v1/packages/{packageId}/versions/{versionId}/validation/documents/{fileId}/details
4. The system displays a split screen layout with the following content:
   • Left panel: Displays a table of validation results with the following columns:
     • Type: Indicates the severity level (Error, Warning, Info).
     • Message: Describes the validation issue.
   • Each validation result includes a message text explaining the issue.
5. User clicks on a validation message on the left panel.
6. The system highlights the corresponding line in the API spec on the right panel, allowing navigation and automatically scrolls to it, helping the user quickly locate the issue in the code.
7. The system also shows the validation ruleset name and status above the left panel, under the "Validated by" label.
8. User clicks the ruleset name:
9. The system opens a popup containing:
   • The full name of the ruleset
   • A clickable link to download the ruleset YAML file.
   • The activation history for that ruleset, listed as date ranges.
   • API: GET /api/v1/rulesets/{id}