chore: define model of import report

Closes #960

modules/importer/src/model/mod.rs

@@ -15,6 +15,7 @@ pub use cwe::*;
 pub use osv::*;
 pub use sbom::*;
 
+use crate::runner::report::Report;
 use std::{
     ops::{Deref, DerefMut},
     time::Duration,
@@ -251,15 +252,20 @@ impl TryFrom<Model> for Importer {
 #[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct ImporterReport {
+    /// The ID of the report
     pub id: String,
 
+    /// The name of the importer this report belongs to
     pub importer: String,
+    /// The time the report was created
     #[serde(with = "time::serde::rfc3339")]
     pub creation: OffsetDateTime,
 
+    /// Errors captured by the report
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub error: Option<String>,
-    pub report: serde_json::Value,
+    /// Detailed report information
+    pub report: Option<Report>,
 }
 
 impl From<importer_report::Model> for ImporterReport {
@@ -276,7 +282,7 @@ impl From<importer_report::Model> for ImporterReport {
             importer,
             creation,
             error,
-            report,
+            report: serde_json::from_value(report).ok(),
         }
     }
 }

modules/importer/src/runner/report.rs

@@ -1,10 +1,22 @@
 use crate::server::RunOutput;
 use parking_lot::Mutex;
+use schemars::JsonSchema;
 use std::{collections::BTreeMap, iter, sync::Arc};
 use time::OffsetDateTime;
 
+/// The phase of processing
 #[derive(
-    Copy, Clone, Debug, PartialEq, Eq, Ord, PartialOrd, serde::Deserialize, serde::Serialize,
+    Copy,
+    Clone,
+    Debug,
+    PartialEq,
+    Eq,
+    Ord,
+    PartialOrd,
+    serde::Deserialize,
+    serde::Serialize,
+    utoipa::ToSchema,
+    JsonSchema,
 )]
 #[serde(rename_all = "camelCase")]
 pub enum Phase {
@@ -17,31 +29,46 @@ pub enum Phase {
 }
 
 #[derive(
-    Copy, Clone, Debug, PartialEq, Eq, Ord, PartialOrd, serde::Deserialize, serde::Serialize,
+    Copy,
+    Clone,
+    Debug,
+    PartialEq,
+    Eq,
+    Ord,
+    PartialOrd,
+    serde::Deserialize,
+    serde::Serialize,
+    utoipa::ToSchema,
 )]
 #[serde(rename_all = "camelCase")]
 pub enum Severity {
     Error,
     Warning,
 }
 
-#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize, serde::Serialize)]
+#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct Report {
+    /// Start of the import run
     #[serde(with = "time::serde::rfc3339")]
     pub start_date: OffsetDateTime,
+    /// End of the import run
     #[serde(with = "time::serde::rfc3339")]
     pub end_date: OffsetDateTime,
 
+    /// Number of processes items
     #[serde(default, alias = "numer_of_items")]
     pub number_of_items: usize,
+    /// Messages emitted during processing
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub messages: BTreeMap<Phase, BTreeMap<String, Vec<Message>>>,
 }
 
-#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize, serde::Serialize)]
+#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
 pub struct Message {
+    ///  The severity of the message
     pub severity: Severity,
+    /// The message
     pub message: String,
 }
 

openapi.yaml

@@ -2512,20 +2512,27 @@ components:
       - id
       - importer
       - creation
-      - report
       properties:
         creation:
           type: string
           format: date-time
+          description: The time the report was created
         error:
           type:
           - string
           - 'null'
+          description: Errors captured by the report
         id:
           type: string
+          description: The ID of the report
         importer:
           type: string
-        report: {}
+          description: The name of the importer this report belongs to
+        report:
+          oneOf:
+          - type: 'null'
+          - $ref: '#/components/schemas/Report'
+            description: Detailed report information
     IngestResult:
       type: object
       description: The result of the ingestion process
@@ -2573,6 +2580,18 @@ components:
           type: array
           items:
             type: string
+    Message:
+      type: object
+      required:
+      - severity
+      - message
+      properties:
+        message:
+          type: string
+          description: The message
+        severity:
+          $ref: '#/components/schemas/Severity'
+          description: The severity of the message
     MessageType:
       type: string
       enum:
@@ -2715,20 +2734,27 @@ components:
             - id
             - importer
             - creation
-            - report
             properties:
               creation:
                 type: string
                 format: date-time
+                description: The time the report was created
               error:
                 type:
                 - string
                 - 'null'
+                description: Errors captured by the report
               id:
                 type: string
+                description: The ID of the report
               importer:
                 type: string
-              report: {}
+                description: The name of the importer this report belongs to
+              report:
+                oneOf:
+                - type: 'null'
+                - $ref: '#/components/schemas/Report'
+                  description: Detailed report information
         total:
           type: integer
           format: int64
@@ -3197,6 +3223,42 @@ components:
       - dev_tool_of
       - described_by
       - package_of
+    Report:
+      type: object
+      required:
+      - startDate
+      - endDate
+      properties:
+        endDate:
+          type: string
+          format: date-time
+          description: End of the import run
+        messages:
+          type: object
+          description: Messages emitted during processing
+          additionalProperties:
+            type: object
+            additionalProperties:
+              type: array
+              items:
+                $ref: '#/components/schemas/Message'
+            propertyNames:
+              type: string
+          propertyNames:
+            type: string
+            description: The phase of processing
+            enum:
+            - retrieval
+            - validation
+            - upload
+        numberOfItems:
+          type: integer
+          description: Number of processes items
+          minimum: 0
+        startDate:
+          type: string
+          format: date-time
+          description: Start of the import run
     Revisioned_Importer:
       type: object
       description: |-