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 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 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, then the system disables API Quality tab and shows tooltip on hover: "API quality check in progress"
   • If the validation status is noResults, then the system disables API Quality tab and shows tooltip on hover: "No API quality check result"
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).
       • Message column: Describes the validation issue.
     • content of the validated document.
       • API to fetch the raw document content - GET /api/v2/packages/{packageId}/versions/{version}/files/{documentId}/raw
     • ruleset against which version was validated.
   • API to show validation result - GET /api/v1/packages/{packageId}/versions/{versionId}/validation/documents/{fileId}/details:
     • packageId - current package id
     • versionId - current version id
     • fileId - currently selected document.
3. User clicks on dropdown field with documents.
4. The system show list of OpenAPI documents that were validated by linter service.
   • API to get list of documents: GET /api/v1/packages/{packageId}/versions/{versionId}/validation/documents
     • packageId - current package id
     • versionId - current version id
5. User types some value in search field in documents dropdown field.
6. The system searches (client side) documents by title and shows only appropriate documents.
7. User selects document.
8. The system shows validation result for the selected document (the same as in step 2).
9. User clicks on a validation message on the left panel.
10. The system scrolls document content to the place with the selected issue and highlights the corresponding line.
11. User clicks JSON or YAML in format switcher (by default YAML is selected).
12. The system shows document's content in the selected format.
13. User clicks the ruleset name near "Validated by".
14. The system opens a popup containing:
    • The name of the ruleset and its status.
    • A clickable link to download the ruleset YAML file.
    • The activation history for that ruleset, listed as date ranges.
15. In the popup the system clicks on the file.
16. The system downloads the ruleset file.
    • API to download file: GET /api/v1/rulesets/{id}