1 files changed, 131 insertions, 2 deletions
diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md
index 36604ebf87d..20bbe66549d 100644
--- a/doc/api/vulnerability_findings.md
+++ b/doc/api/vulnerability_findings.md
@@ -25,9 +25,11 @@ If a user is able to access the project but does not have permission to
 any request for vulnerability findings of this project results in a `403` status code.
 
 WARNING:
-This API is in an alpha stage and considered unstable.
+This API is in the process of being deprecated and considered unstable.
 The response payload may be subject to change or breakage
-across GitLab releases.
+across GitLab releases. Please use the
+[GraphQL API](graphql/reference/index.md#queryvulnerabilities)
+instead. See the [GraphQL examples](#replace-vulnerability-findings-rest-api-with-graphql) to get started.
 
 ## Vulnerability findings pagination
 
@@ -137,3 +139,130 @@ Example response:
   }
 ]
 ```
+
+## Replace Vulnerability Findings REST API with GraphQL
+
+To prepare for the [upcoming deprecation](https://gitlab.com/groups/gitlab-org/-/epics/5118) of
+the Vulnerability Findings REST API endpoint, use the examples below to perform the equivalent operations
+with the GraphQL API.
+
+### GraphQL - Project vulnerabilities
+
+Use [`Project.vulnerabilities`](graphql/reference/#projectvulnerabilities).
+
+```graphql
+{
+  project(fullPath: "root/security-reports") {
+    vulnerabilities {
+      nodes{
+        id
+        reportType
+        title
+        severity
+        scanner {
+          externalId
+          name
+          vendor
+        }
+        identifiers {
+          externalType
+          externalId
+          name
+          url
+        }
+        falsePositive
+        project {
+          id
+          name
+          fullPath
+        }
+        description
+        links {
+          name
+          url
+        }
+        location {
+          ... on
+          VulnerabilityLocationSast {
+            file
+            startLine
+            endLine
+            vulnerableClass
+            vulnerableMethod
+            blobPath
+          }
+        }
+        details {
+          ... on
+          VulnerabilityDetailCode {
+            description
+            fieldName
+            lang
+            name
+            value
+          }
+        }
+        state
+      }
+    }
+  }
+}
+```
+
+Example response:
+
+```json
+{
+  "data": {
+    "project": {
+      "vulnerabilities": {
+        "nodes": [
+          {
+            "id": "gid://gitlab/Vulnerability/236",
+            "reportType": "SAST",
+            "title": "Generic Object Injection Sink",
+            "severity": "CRITICAL",
+            "scanner": {
+              "externalId": "eslint",
+              "name": "ESLint",
+              "vendor": "GitLab"
+            },
+            "identifiers": [
+              {
+                "externalType": "eslint_rule_id",
+                "externalId": "security/detect-object-injection",
+                "name": "ESLint rule ID security/detect-object-injection",
+                "url": "https://github.com/nodesecurity/eslint-plugin-security#detect-object-injection"
+              },
+              {
+                "externalType": "cwe",
+                "externalId": "94",
+                "name": "CWE-94",
+                "url": "https://cwe.mitre.org/data/definitions/94.html"
+              }
+            ],
+            "falsePositive": false,
+            "project": {
+              "id": "gid://gitlab/Project/20",
+              "name": "Security Reports",
+              "fullPath": "root/security-reports"
+            },
+            "description": "Bracket object notation with user input is present, this might allow an attacker to access all properties of the object and even it's prototype, leading to possible code execution.",
+            "links": [],
+            "location": {
+              "file": "src/js/main.js",
+              "startLine": "28",
+              "endLine": "28",
+              "vulnerableClass": null,
+              "vulnerableMethod": null,
+              "blobPath": "/root/security-reports/-/blob/91031428a5b5dbb81e8d889738b1875c1bfea787/src/js/main.js"
+            },
+            "details": [],
+            "state": "DETECTED"
+          }
+        ]
+      }
+    }
+  }
+}
+```