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)
• Run manual validation for a package version (POST /api/v1/packages/{packageId}/versions/{version}/validation/summary)
• Get validation details for a specific document (GET /api/v1/packages/{packageId}/versions/{version}/validation/documents/{slug}/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 by qubership-api-linter-service.

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

1. The system verifies whether the qubership-api-linter-service is enabled:
   • API to check of linter service is enabled - GET /system/info
     • if linterEnabled = true, then it means linter service is enabled.
2. If linter service is disabled, the API Quality 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 rulesets used for validation, API type and its status.
     • Number of quality issues: Number of issues of each type - Errors, Warnings, Info and Hints.
     • If there are inactive rulesets (rulesets that were used but are now inactive):
       • The system shows a "Run Validation" button to re-validate with current active rulesets
       • API: POST /api/v1/packages/{packageId}/versions/{version}/validation/summary
   • If package version does not have validation result:
     • The system displays the following static message under Quality Validation: "No validation results."
     • The system shows a "Run Validation" button to start validation
   • If linter service is still processing validation:
     • The system displays the following message: "Validation is in progress, please wait...".
   • If validation is failed:
     • The system shows error icon and shows tooltip on hover: "Validation failed. Some documents could not be processed during quality validation"
     • Validation ruleset: Name of the rulesets used for validation, API type and its status.
     • Number of failed documents: Displays the count of documents that failed validation. Hover over the info icon to see a tooltip with the list of failed document names.
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.
     • API type and Status
     • Download link: A clickable link that allows the user to download the YAML file of the ruleset.
     • Copy link: A clickable link that allows the user to copy the public URL of the ruleset in YAML format.
     • Activation history: A list of activation periods for the ruleset, displayed as date ranges.
     • API: GET /api/v1/rulesets/{id}/activation

To view validation results:

1. User clicks on the API Quality tab.
   • If the validation status is inProgress, then the system disables API Quality tab and shows tooltip on hover: "API quality check in progress"
   • If the validation status is failed, then the system disables API Quality tab and shows tooltip on hover: "API quality check is not available"
2. The system opens Quality Validation page and shows validation results of the selected document. By default the first document is preselected.
   • The system displays the following information:
     • table with issues found in the selected document:
       • Type column: Indicates the severity level (Error, Warning, Info, Hint).
       • Message column: Describes the validation issue.
       • Sorting of validation issues:
         • By severity: 'error' -> 'warning' -> 'info' -> 'hint'.
         • Within the same severity by document position from start to end.
     • content of the validated document.
     • ruleset against which version was validated, API type and status.
       • User clicks the ruleset name.
       • The system opens a popup containing:
         • The name of the ruleset its API type and status.
         • A clickable link to download the ruleset YAML file.
         • A clickable link to copy the public URL of the ruleset in YAML format.
         • The activation history for that ruleset, listed as date ranges.
   • API to show validation details for a specific document - GET /api/v1/packages/{packageId}/versions/{version}/validation/documents/{slug}/details
3. User clicks on dropdown field with documents.
   • The system show list of OpenAPI documents that were validated by linter service.
4. User types some value in search field in documents dropdown field.
   • The system searches documents by title and shows only appropriate documents.
5. User selects document.
   • The system shows validation result for the selected document (the same as in step 2).

To view validation results in the document content:

1. The system automatically highlights all validation issues in the document content with wavy underlines. The color indicates the issue severity:
   • Red: Error
   • Yellow: Warning
   • Blue: Info
   • Gray: Hint
2. User clicks on a validation message in the left panel.
   • The system scrolls to the corresponding issue in the document content and marks the affected code block with a vertical blue line.
3. User hovers over a wavy underline in the document content.
   • The system displays a tooltip with the issue description.
4. User clicks "View Problem (Alt+F8)" in the tooltip.
   • The system opens a modal window with a color matching the issue severity.
   • The modal highlights the exact location of the issue (the specific line or keyword where the error occurs).
5. User clicks JSON or YAML in the format switcher (YAML is selected by default).
   • The system displays the document content in the selected format.