docs: support deprecated in API reference (#12438)

www/apps/api-reference/components/Tags/Operation/DescriptionSection/DeprecationNotice/index.tsx

@@ -0,0 +1,27 @@
+import clsx from "clsx"
+import { Badge, Tooltip } from "docs-ui"
+
+export type TagsOperationDescriptionSectionDeprecationNoticeProps = {
+  deprecationMessage?: string
+  className?: string
+}
+
+const TagsOperationDescriptionSectionDeprecationNotice = ({
+  deprecationMessage,
+  className,
+}: TagsOperationDescriptionSectionDeprecationNoticeProps) => {
+  const getBadge = () => {
+    return <Badge variant="orange">deprecated</Badge>
+  }
+
+  return (
+    <div className={clsx("inline-block", className)}>
+      {deprecationMessage && (
+        <Tooltip text={deprecationMessage}>{getBadge()}</Tooltip>
+      )}
+      {!deprecationMessage && getBadge()}
+    </div>
+  )
+}
+
+export default TagsOperationDescriptionSectionDeprecationNotice

www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx

@@ -12,6 +12,7 @@ import { Feedback, Badge, Link, FeatureFlagNotice, H2, Tooltip } from "docs-ui"
 import { usePathname } from "next/navigation"
 import { TagsOperationDescriptionSectionWorkflowBadgeProps } from "./WorkflowBadge"
 import { TagsOperationDescriptionSectionEventsProps } from "./Events"
+import { TagsOperationDescriptionSectionDeprecationNoticeProps } from "./DeprecationNotice"
 
 const TagsOperationDescriptionSectionSecurity =
   dynamic<TagsOperationDescriptionSectionSecurityProps>(
@@ -38,6 +39,11 @@ const TagsOperationDescriptionSectionEvents =
     async () => import("./Events")
   ) as React.FC<TagsOperationDescriptionSectionEventsProps>
 
+const TagsOperationDescriptionSectionDeprecationNotice =
+  dynamic<TagsOperationDescriptionSectionDeprecationNoticeProps>(
+    async () => import("./DeprecationNotice")
+  ) as React.FC<TagsOperationDescriptionSectionDeprecationNoticeProps>
+
 type TagsOperationDescriptionSectionProps = {
   operation: OpenAPI.Operation
 }
@@ -52,9 +58,10 @@ const TagsOperationDescriptionSection = ({
       <H2>
         {operation.summary}
         {operation.deprecated && (
-          <Badge variant="orange" className="ml-0.5">
-            deprecated
-          </Badge>
+          <TagsOperationDescriptionSectionDeprecationNotice
+            deprecationMessage={operation["x-deprecated_message"]}
+            className="ml-0.5"
+          />
         )}
         {operation["x-featureFlag"] && (
           <FeatureFlagNotice

www/packages/types/src/openapi.ts

@@ -24,6 +24,7 @@ export type Operation = OpenAPIV3.OperationObject<{
   "x-sidebar-summary"?: string
   "x-events"?: OasEvents[]
   "x-version"?: string
+  "x-deprecated_message"?: string
 }>
 
 export type RequestObject = OpenAPIV3.RequestBodyObject & {

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)
   }
 

www/utils/packages/docs-generator/src/types/index.d.ts

@@ -11,6 +11,8 @@ export declare type OpenApiOperation = Partial<OpenAPIV3.OperationObject> & {
   "x-codeSamples"?: CodeSample[]
   "x-workflow"?: string
   "x-events"?: OasEvent[]
+  "x-deprecated_message"?: string
+  "x-version"?: string
 }
 
 export declare type CommonCliOptions = {