Update OpenAPI docs

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: dependencytrack-bot

docs/reference/api/openapi-v1.yaml

@@ -65,6 +65,29 @@ info:
     The total number of items in the collection across all pages is
     returned in the `X-Total-Count` response header.
 
+    ### Bounded total counts
+
+    An exact `X-Total-Count` gets more expensive as a collection grows, and on large
+    collections it can time out. Some endpoints therefore accept an optional `totalCount`
+    query parameter that caps the cost of counting:
+
+    | `totalCount` | Description                                                        |
+    |--------------|--------------------------------------------------------------------|
+    | `EXACT`      | Count every matching item. The default. Can time out.              |
+    | `BOUNDED`    | Stop counting at a server-side cap. May return only a lower bound. |
+
+    Any other value is rejected with `400`. Each endpoint documents how it computes the
+    bounded count, on its `totalCount` parameter.
+
+    Endpoints that accept `totalCount` also return an `X-Total-Count-Type` header saying
+    how to read `X-Total-Count`. They return it on every collection response, including
+    ones that did not opt in.
+
+    | `X-Total-Count-Type` | Meaning                                                              |
+    |----------------------|----------------------------------------------------------------------|
+    | `EXACT`              | `X-Total-Count` is the true total.                                   |
+    | `AT_LEAST`           | `X-Total-Count` is only a lower bound. The true total may be higher. |
+
     ## HTTP Methods
 
     | Method   | Semantics                                |
@@ -86,6 +109,15 @@ info:
 
     Delete (`DELETE`) operations typically return `204 No Content`.
 
+    ## Timeouts
+
+    A request that takes too long to complete is aborted and answered
+    with `504 Gateway Timeout` and a problem details body. Any operation
+    can time out, so operations do not document it individually.
+
+    Requesting a bounded total count can avoid the timeout where the
+    operation supports it, because counting is often the expensive part.
+
     ## Deprecations
 
     Operations may be removed or replaced over time. When a response
@@ -2028,6 +2060,21 @@ paths:
         name: isKev
         schema:
           type: boolean
+      - description: "The counting mode for `X-Total-Count`. With `BOUNDED`, the count\
+          \ stops at a fixed server-side cap. `X-Total-Count` is then exact when the\
+          \ count finishes within the cap, or when the requested page ends the result\
+          \ set. Otherwise it is a lower bound, never below the end of the requested\
+          \ page. `X-Total-Count-Type` says which case applies. See the Pagination\
+          \ section of the API description."
+        in: query
+        name: totalCount
+        schema:
+          type: string
+          default: EXACT
+          description: The counting mode for the `X-Total-Count` response header.
+          enum:
+          - EXACT
+          - BOUNDED
       responses:
         "200":
           content:
@@ -2039,10 +2086,19 @@ paths:
           description: A list of all findings
           headers:
             X-Total-Count:
-              description: The total number of findings
+              description: "The number of findings, exact or a lower bound. See `X-Total-Count-Type`."
               schema:
                 format: integer
               style: simple
+            X-Total-Count-Type:
+              $ref: "#/components/headers/TotalCountType"
+              style: simple
+        "400":
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+          description: Invalid query parameter
         "401":
           description: Unauthorized
       security:
@@ -2189,6 +2245,21 @@ paths:
         name: isKev
         schema:
           type: boolean
+      - description: "The counting mode for `X-Total-Count`. With `BOUNDED`, the count\
+          \ is skipped and `X-Total-Count` reports what the requested page itself\
+          \ proves. `X-Total-Count-Type` is then `EXACT` when the page ends the result\
+          \ set, and `AT_LEAST` otherwise. A page past the end reports `AT_LEAST`\
+          \ with a count of 0, which means the total is unknown. See the Pagination\
+          \ section of the API description."
+        in: query
+        name: totalCount
+        schema:
+          type: string
+          default: EXACT
+          description: The counting mode for the `X-Total-Count` response header.
+          enum:
+          - EXACT
+          - BOUNDED
       responses:
         "200":
           content:
@@ -2200,10 +2271,19 @@ paths:
           description: A list of all findings grouped by vulnerability
           headers:
             X-Total-Count:
-              description: The total number of findings
+              description: "The number of findings, exact or a lower bound. See `X-Total-Count-Type`."
               schema:
                 format: integer
               style: simple
+            X-Total-Count-Type:
+              $ref: "#/components/headers/TotalCountType"
+              style: simple
+        "400":
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+          description: Invalid query parameter
         "401":
           description: Unauthorized
       security:
@@ -2315,6 +2395,21 @@ paths:
         name: isKev
         schema:
           type: boolean
+      - description: "The counting mode for `X-Total-Count`. With `BOUNDED`, the count\
+          \ stops at a fixed server-side cap. `X-Total-Count` is then exact when the\
+          \ count finishes within the cap, or when the requested page ends the result\
+          \ set. Otherwise it is a lower bound, never below the end of the requested\
+          \ page. `X-Total-Count-Type` says which case applies. See the Pagination\
+          \ section of the API description."
+        in: query
+        name: totalCount
+        schema:
+          type: string
+          default: EXACT
+          description: The counting mode for the `X-Total-Count` response header.
+          enum:
+          - EXACT
+          - BOUNDED
       responses:
         "200":
           content:
@@ -2327,13 +2422,22 @@ paths:
               schema:
                 type: string
           description: "A list of all findings for a specific project, or a SARIF\
-            \ file"
+            \ file. SARIF responses carry no count headers."
           headers:
             X-Total-Count:
-              description: The total number of findings
+              description: "The number of findings, exact or a lower bound. See `X-Total-Count-Type`."
               schema:
                 format: integer
               style: simple
+            X-Total-Count-Type:
+              $ref: "#/components/headers/TotalCountType"
+              style: simple
+        "400":
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+          description: Invalid query parameter
         "401":
           description: Unauthorized
         "403":
@@ -7638,8 +7742,52 @@ paths:
       - team
   /v1/team/visible:
     get:
-      description: <p></p>
+      description: <p>Optional query parameter <code>searchText</code>. The search
+        is case insensitive and matches team names.</p>
       operationId: availableTeams
+      parameters:
+      - description: Optional case-insensitive substring match on team name.
+        in: query
+        name: searchText
+        schema:
+          type: string
+      - description: The page to return. To be used in conjunction with <code>pageSize</code>.
+        in: query
+        name: pageNumber
+        schema:
+          type: string
+          default: "1"
+      - description: Number of elements to return per page. To be used in conjunction
+          with <code>pageNumber</code>.
+        in: query
+        name: pageSize
+        schema:
+          type: string
+          default: "100"
+      - description: Offset to start returning elements from. To be used in conjunction
+          with <code>limit</code>.
+        in: query
+        name: offset
+        schema:
+          type: string
+      - description: Number of elements to return per page. To be used in conjunction
+          with <code>offset</code>.
+        in: query
+        name: limit
+        schema:
+          type: string
+      - description: Name of the resource field to sort on.
+        in: query
+        name: sortName
+        schema:
+          type: string
+      - description: Ordering of items when sorting with <code>sortName</code>.
+        in: query
+        name: sortOrder
+        schema:
+          type: string
+          enum:
+          - "asc, desc"
       responses:
         "200":
           content:
@@ -7649,6 +7797,12 @@ paths:
                 items:
                   $ref: "#/components/schemas/VisibleTeams"
           description: The Visible Teams
+          headers:
+            X-Total-Count:
+              description: The total number of visible teams
+              schema:
+                format: integer
+              style: simple
         "401":
           description: Unauthorized
       security:
@@ -9485,6 +9639,15 @@ paths:
       tags:
       - version
 components:
+  headers:
+    TotalCountType:
+      description: Whether `X-Total-Count` is exact (`EXACT`) or a lower bound (`AT_LEAST`).
+        `AT_LEAST` with a count of 0 means the total is unknown.
+      schema:
+        type: string
+        enum:
+        - EXACT
+        - AT_LEAST
   schemas:
     About:
       type: object

docs/reference/api/openapi-v2.yaml

@@ -76,6 +76,10 @@ info:
     }
     ```
 
+    A request that takes too long to complete is aborted and rejected
+    with `504 Gateway Timeout`. Any operation can time out, so operations
+    do not document it individually.
+
     ## Authentication
 
     Two credential types are accepted:
@@ -2832,12 +2836,16 @@ components:
     list-extensions-response-item:
       required:
       - configurable
+      - display_name
       - name
       - testable
       type: object
       properties:
         name:
           type: string
+        display_name:
+          type: string
+          description: Human-readable name of the extension.
         configurable:
           type: boolean
           description: Whether the extension supports runtime configuration.
@@ -3102,6 +3110,7 @@ components:
     kev-assertion:
       required:
       - asserter
+      - asserter_display_name
       - created_at
       - updated_at
       - vuln_id
@@ -3111,7 +3120,10 @@ components:
         asserter:
           type: string
           description: "The entity that asserted the vulnerability is known to be\
-            \ exploited (e.g. `CISA`, `ENISA`)."
+            \ exploited (e.g. `cisa`, `enisa`)."
+        asserter_display_name:
+          type: string
+          description: Human-readable name of the asserting entity (e.g. `CISA KEV`).
         vuln_source:
           type: string
           description: Source of the asserted vulnerability identifier (e.g. `NVD`).