update client/openapi/trustd.yaml

client/openapi/trustd.yaml

@@ -1,11 +1,11 @@
 openapi: 3.1.0
 info:
   title: Trustify
-  description: Software Supply-Chain Security API
+  description: Software Supply-Chain Security API (main)
   license:
     name: Apache License, Version 2.0
     identifier: Apache-2.0
-  version: 0.2.1
+  version: 0.2.6
 paths:
   /.well-known/trustify:
     get:
@@ -230,6 +230,7 @@ paths:
     get:
       tags:
       - analysis
+      summary: Retrieve SBOM components (packages) by a complex search.
       operationId: searchComponent
       parameters:
       - name: q
@@ -266,37 +267,52 @@ paths:
           minimum: 0
       - name: ancestors
         in: query
+        description: |-
+          The level of ancestors to return.
+
+          Zero, the default, meaning none.
         required: false
         schema:
           type: integer
           format: int64
           minimum: 0
       - name: descendants
         in: query
+        description: |-
+          The level of descendants to return.
+
+          Zero, the default, meaning none.
         required: false
         schema:
           type: integer
           format: int64
           minimum: 0
       - name: relationships
         in: query
+        description: |-
+          A set of relationships to filter for, deserialized from a
+          comma-delimited string
+
+          An empty set, the default, meaning all relationships.
         required: false
         schema:
-          type: array
-          items:
-            $ref: '#/components/schemas/Relationship'
-          uniqueItems: true
+          type: string
       responses:
         '200':
-          description: Retrieve component(s) root components by name, pURL, or CPE.
+          description: Retrieved component(s) located by search
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/PaginatedResults_BaseSummary'
+                $ref: '#/components/schemas/PaginatedResults_Node'
+        '401':
+          description: The user did not provide valid authentication credentials
+        '403':
+          description: The user lacks the required permission
   /api/v2/analysis/component/{key}:
     get:
       tags:
       - analysis
+      summary: Retrieve SBOM components (packages) by name, Package URL, or CPE.
       operationId: getComponent
       parameters:
       - name: key
@@ -339,37 +355,52 @@ paths:
           minimum: 0
       - name: ancestors
         in: query
+        description: |-
+          The level of ancestors to return.
+
+          Zero, the default, meaning none.
         required: false
         schema:
           type: integer
           format: int64
           minimum: 0
       - name: descendants
         in: query
+        description: |-
+          The level of descendants to return.
+
+          Zero, the default, meaning none.
         required: false
         schema:
           type: integer
           format: int64
           minimum: 0
       - name: relationships
         in: query
+        description: |-
+          A set of relationships to filter for, deserialized from a
+          comma-delimited string
+
+          An empty set, the default, meaning all relationships.
         required: false
         schema:
-          type: array
-          items:
-            $ref: '#/components/schemas/Relationship'
-          uniqueItems: true
+          type: string
       responses:
         '200':
-          description: Retrieve component(s) root components by name, pURL, or CPE.
+          description: Retrieved component(s) located by name, pURL, or CPE
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/PaginatedResults_BaseSummary'
-  /api/v2/analysis/sbom/{sbom}/render:
+                $ref: '#/components/schemas/PaginatedResults_Node'
+        '401':
+          description: The user did not provide valid authentication credentials
+        '403':
+          description: The user lacks the required permission
+  /api/v2/analysis/sbom/{sbom}/render.{ext}:
     get:
       tags:
       - analysis
+      summary: Render an SBOM graph
       operationId: renderSbomGraph
       parameters:
       - name: sbom
@@ -378,27 +409,46 @@ paths:
         required: true
         schema:
           type: string
+      - name: ext
+        in: path
+        description: Renderer to use
+        required: true
+        schema:
+          type: string
+          enum:
+          - gv
       responses:
         '200':
-          description: A graphviz dot file of the SBOM graph
+          description: A rendered version of the SBOM graph in the format requested
           content:
             text/plain:
               schema:
                 type: string
+        '401':
+          description: The user did not provide valid authentication credentials
+        '403':
+          description: The user lacks the required permission
         '404':
           description: The SBOM was not found
+        '415':
+          description: Unsupported rendering format
   /api/v2/analysis/status:
     get:
       tags:
       - analysis
+      summary: Get the status of the analysis service.
       operationId: status
       responses:
         '200':
-          description: Analysis status.
+          description: Analysis status
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AnalysisStatus'
+        '401':
+          description: The user did not provide valid authentication credentials
+        '403':
+          description: The user lacks the required permission
   /api/v2/dataset:
     post:
       tags:
@@ -2535,6 +2585,30 @@ components:
         severity:
           $ref: '#/components/schemas/Severity'
           description: The severity of the message
+    Node:
+      allOf:
+      - $ref: '#/components/schemas/BaseSummary'
+      - type: object
+        properties:
+          ancestors:
+            type:
+            - array
+            - 'null'
+            items:
+              $ref: '#/components/schemas/Node'
+            description: All ancestors of this node. [`None`] if not requested on this level.
+          descendants:
+            type:
+            - array
+            - 'null'
+            items:
+              $ref: '#/components/schemas/Node'
+            description: All descendents of this node. [`None`] if not requested on this level.
+          relationship:
+            oneOf:
+            - type: 'null'
+            - $ref: '#/components/schemas/Relationship'
+              description: The relationship the node has to it's containing node, if any.
     OrganizationDetails:
       allOf:
       - $ref: '#/components/schemas/OrganizationHead'
@@ -2667,56 +2741,6 @@ components:
           type: integer
           format: int64
           minimum: 0
-    PaginatedResults_BaseSummary:
-      type: object
-      required:
-      - items
-      - total
-      properties:
-        items:
-          type: array
-          items:
-            type: object
-            required:
-            - sbom_id
-            - node_id
-            - purl
-            - cpe
-            - name
-            - version
-            - published
-            - document_id
-            - product_name
-            - product_version
-            properties:
-              cpe:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Cpe'
-              document_id:
-                type: string
-              name:
-                type: string
-              node_id:
-                type: string
-              product_name:
-                type: string
-              product_version:
-                type: string
-              published:
-                type: string
-              purl:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Purl'
-              sbom_id:
-                type: string
-              version:
-                type: string
-        total:
-          type: integer
-          format: int64
-          minimum: 0
     PaginatedResults_ImporterReport:
       type: object
       required:
@@ -2793,6 +2817,42 @@ components:
           type: integer
           format: int64
           minimum: 0
+    PaginatedResults_Node:
+      type: object
+      required:
+      - items
+      - total
+      properties:
+        items:
+          type: array
+          items:
+            allOf:
+            - $ref: '#/components/schemas/BaseSummary'
+            - type: object
+              properties:
+                ancestors:
+                  type:
+                  - array
+                  - 'null'
+                  items:
+                    $ref: '#/components/schemas/Node'
+                  description: All ancestors of this node. [`None`] if not requested on this level.
+                descendants:
+                  type:
+                  - array
+                  - 'null'
+                  items:
+                    $ref: '#/components/schemas/Node'
+                  description: All descendents of this node. [`None`] if not requested on this level.
+                relationship:
+                  oneOf:
+                  - type: 'null'
+                  - $ref: '#/components/schemas/Relationship'
+                    description: The relationship the node has to it's containing node, if any.
+        total:
+          type: integer
+          format: int64
+          minimum: 0
     PaginatedResults_ProductSummary:
       type: object
       required: