From 07ca12e3df5d805b40fd6008efeb83e4352af2a9 Mon Sep 17 00:00:00 2001
From: dependencytrack-bot
 <106437498+dependencytrack-bot@users.noreply.github.com>
Date: Sat, 25 Apr 2026 14:30:46 +0000
Subject: [PATCH] Update OpenAPI docs

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 docs/reference/api/openapi-v1.yaml | 18 ++++++++++++++++--
 docs/reference/api/openapi-v2.yaml | 10 ++++++++++
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/reference/api/openapi-v1.yaml b/docs/reference/api/openapi-v1.yaml
index cd72376..7d2dc9a 100644
--- a/docs/reference/api/openapi-v1.yaml
+++ b/docs/reference/api/openapi-v1.yaml
@@ -3,7 +3,18 @@ info:
   contact:
     name: The Dependency-Track Authors
     url: https://github.com/DependencyTrack/dependency-track
-  description: REST API of OWASP Dependency-Track
+  description: |-
+    REST API of OWASP Dependency-Track
+
+    ## Deprecations
+
+    Operations may be removed or replaced over time. When a response
+    carries the `X-API-Deprecated: true` header, the operation that
+    produced it is deprecated and may be removed in a future release.
+    Clients should check for this header on every response and surface
+    it (e.g. via a log warning) so that operators are aware of
+    upcoming breakages. The respective operation's description points
+    out which alternative operation(s) to use.
   license:
     name: Apache-2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -8684,7 +8695,10 @@ paths:
       - vulnerability
   /v1/vulnerability/project/{uuid}:
     get:
-      description: <p>Requires permission <strong>VIEW_PORTFOLIO</strong></p>
+      deprecated: true
+      description: |-
+        <p>Requires permission <strong>VIEW_PORTFOLIO</strong></p>
+        <p><strong>Deprecated</strong>! Use <code>/api/v1/finding/project/{uuid}</code> instead.</p>
       operationId: getVulnerabilitiesByProject
       parameters:
       - description: The UUID of the project to retrieve vulnerabilities for
diff --git a/docs/reference/api/openapi-v2.yaml b/docs/reference/api/openapi-v2.yaml
index 047e4cf..80dc297 100644
--- a/docs/reference/api/openapi-v2.yaml
+++ b/docs/reference/api/openapi-v2.yaml
@@ -85,6 +85,16 @@ info:
     created resource.
 
     Delete operations return `204 No Content` with no body.
+
+    ## Deprecations
+
+    Operations may be removed or replaced over time. When a response
+    carries the `X-API-Deprecated: true` header, the operation that
+    produced it is deprecated and may be removed in a future release.
+    Clients should check for this header on every response and surface
+    it (e.g. via a log warning) so that operators are aware of upcoming
+    breakages. The respective operation's description points out which
+    alternative operation(s) to use.
   contact:
     name: The Dependency-Track Authors
     url: https://github.com/DependencyTrack/dependency-track