docs: support deprecated in API reference (#12438)

www/utils/packages/docs-generator/src/classes/kinds/default.ts

@@ -595,6 +595,42 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
   nodeHasComments(node: ts.Node): boolean {
     return this.getNodeCommentsFromRange(node) !== undefined
   }
+
+  /**
+   * Retrieve information from the tags of a node.
+   *
+   * @param node - The node to retrieve the information from.
+   * @returns An object containing the deprecated and version tags, if available.
+   */
+  getInformationFromTags(node: ts.Node): {
+    deprecatedTag: ts.JSDocTag | undefined
+    versionTag: ts.JSDocTag | undefined
+  } {
+    const nodeComments = ts.getJSDocCommentsAndTags(node)
+    let deprecatedTag: ts.JSDocTag | undefined
+    let versionTag: ts.JSDocTag | undefined
+
+    nodeComments.forEach((comment) => {
+      if (!("tags" in comment)) {
+        return
+      }
+
+      comment.tags?.forEach((tag) => {
+        if (tag.tagName.getText() === "deprecated") {
+          deprecatedTag = tag
+        }
+
+        if (tag.tagName.getText() === "version") {
+          versionTag = tag
+        }
+      })
+    })
+
+    return {
+      deprecatedTag,
+      versionTag,
+    }
+  }
 }
 
 export default DefaultKindGenerator

www/utils/packages/docs-generator/src/classes/kinds/oas.ts

@@ -434,6 +434,22 @@ class OasKindGenerator extends FunctionKindGenerator {
       oas["x-events"] = this.getOasEvents(oas["x-workflow"])
     }
 
+    // check deprecation and version in tags
+    const { deprecatedTag, versionTag } = this.getInformationFromTags(node)
+
+    if (deprecatedTag) {
+      oas.deprecated = true
+      oas["x-deprecated_message"] = deprecatedTag.comment
+        ? (deprecatedTag.comment as string)
+        : undefined
+    }
+
+    if (versionTag) {
+      oas["x-version"] = versionTag.comment
+        ? (versionTag.comment as string)
+        : undefined
+    }
+
     return formatOas(oas, oasPrefix)
   }
 
@@ -767,6 +783,27 @@ class OasKindGenerator extends FunctionKindGenerator {
       oas["x-events"] = this.getOasEvents(oas["x-workflow"])
     }
 
+    // check deprecation and version in tags
+    const { deprecatedTag, versionTag } = this.getInformationFromTags(node)
+
+    if (deprecatedTag) {
+      oas.deprecated = true
+      oas["x-deprecated_message"] = deprecatedTag.comment
+        ? (deprecatedTag.comment as string)
+        : undefined
+    } else {
+      delete oas.deprecated
+      delete oas["x-deprecated_message"]
+    }
+
+    if (versionTag) {
+      oas["x-version"] = versionTag.comment
+        ? (versionTag.comment as string)
+        : undefined
+    } else {
+      delete oas["x-version"]
+    }
+
     return formatOas(oas, oasPrefix)
   }