[api-documenter] Add support for @DefaultValue in Markdown and Yaml documenters (#5733)

* feat(api-documenter): add support for @DefaultValue in Markdown and Yaml documenters

* change: add rush change file for api-documenter

Author: colinaaa

apps/api-documenter/src/documenters/MarkdownDocumenter.ts

@@ -273,6 +273,7 @@ export class MarkdownDocumenter {
       case ApiItemKind.Function:
         this._writeParameterTables(output, apiItem as ApiParameterListMixin);
         this._writeThrowsSection(output, apiItem);
+        this._writeDefaultValueSection(output, apiItem);
         break;
       case ApiItemKind.Namespace:
         this._writePackageOrNamespaceTables(output, apiItem as ApiNamespace);
@@ -285,10 +286,13 @@ export class MarkdownDocumenter {
         break;
       case ApiItemKind.Property:
       case ApiItemKind.PropertySignature:
+        this._writeDefaultValueSection(output, apiItem);
         break;
       case ApiItemKind.TypeAlias:
+        this._writeDefaultValueSection(output, apiItem);
         break;
       case ApiItemKind.Variable:
+        this._writeDefaultValueSection(output, apiItem);
         break;
       default:
         throw new Error('Unsupported API item kind: ' + apiItem.kind);
@@ -469,6 +473,30 @@ export class MarkdownDocumenter {
     }
   }
 
+  private _writeDefaultValueSection(output: DocSection, apiItem: ApiItem): void {
+    const configuration: TSDocConfiguration = this._tsdocConfiguration;
+
+    if (apiItem instanceof ApiDocumentedItem) {
+      const tsdocComment: DocComment | undefined = apiItem.tsdocComment;
+
+      if (tsdocComment) {
+        // Write the @defaultValue blocks
+        const defaultValueBlocks: DocBlock[] = tsdocComment.customBlocks.filter(
+          (x) => x.blockTag.tagNameWithUpperCase === StandardTags.defaultValue.tagNameWithUpperCase
+        );
+
+        if (defaultValueBlocks.length > 0) {
+          const heading: string = 'Default Value';
+          output.appendNode(new DocHeading({ configuration, title: heading }));
+
+          for (const defaultValueBlock of defaultValueBlocks) {
+            this._appendSection(output, defaultValueBlock.content);
+          }
+        }
+      }
+    }
+  }
+
   /**
    * GENERATE PAGE: MODEL
    */

apps/api-documenter/src/documenters/YamlDocumenter.ts

@@ -427,6 +427,18 @@ export class YamlDocumenter {
             yamlItem.example = [...(yamlItem.example || []), example];
           }
         }
+
+        // Write the @defaultValue block
+        const defaultValueBlocks: DocBlock[] = tsdocComment.customBlocks.filter(
+          (x) => x.blockTag.tagNameWithUpperCase === StandardTags.defaultValue.tagNameWithUpperCase
+        );
+
+        for (const defaultValueBlock of defaultValueBlocks) {
+          const defaultValueContent: string = this._renderMarkdown(defaultValueBlock.content, apiItem);
+          if (defaultValueContent) {
+            yamlItem.defaultValue = defaultValueContent.trim();
+          }
+        }
       }
 
       if (tsdocComment.deprecatedBlock) {

apps/api-documenter/src/utils/ToSdpConvertHelper.ts

@@ -304,6 +304,10 @@ function convertCommonYamlModel(
     result.example = [];
   }
 
+  if (element.defaultValue) {
+    result.defaultValue = element.defaultValue;
+  }
+
   result.isPreview = element.isPreview;
   if (!result.isPreview) {
     result.isPreview = false;

apps/api-documenter/src/yaml/ISDPYamlFile.ts

@@ -16,6 +16,7 @@ export type CommonYamlModel = IBaseYamlModel & {
   remarks?: string;
   example?: string[];
   customDeprecatedMessage?: string;
+  defaultValue?: string;
 };
 
 export type PackageYamlModel = CommonYamlModel & {

apps/api-documenter/src/yaml/IYamlApiFile.ts

@@ -327,6 +327,12 @@ export interface IYamlItem {
    * NOTE: This is an extension and corresponds to `ItemViewModel.Metadata` in DocFX.
    */
   package?: string;
+
+  /**
+   * The default value for the item.
+   * NOTE: This is an extension and corresponds to `ItemViewModel.Metadata` in DocFX.
+   */
+  defaultValue?: string;
 }
 
 /**

apps/api-documenter/src/yaml/typescript.schema.json

@@ -262,6 +262,9 @@
         },
         "package": {
           "type": "string"
+        },
+        "defaultValue": {
+          "type": "string"
         }
       },
       "patternProperties": {

build-tests/api-documenter-test/etc/api-documenter-test.api.json

@@ -592,7 +592,7 @@
             {
               "kind": "Method",
               "canonicalReference": "api-documenter-test!DocClass1#exampleFunction:member(2)",
-              "docComment": "/**\n * This is also an overloaded function.\n *\n * @param x - the number\n */\n",
+              "docComment": "/**\n * This is also an overloaded function.\n *\n * @param x - the number\n *\n * @defaultValue 123\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -2119,7 +2119,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "api-documenter-test!IDocInterface5#regularProperty:member",
-              "docComment": "/**\n * Property of type string that does something\n */\n",
+              "docComment": "/**\n * Property of type string that does something\n *\n * @defaultValue \"Hello World\"\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

build-tests/api-documenter-test/src/DocClass1.ts

@@ -219,6 +219,8 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter
   /**
    * This is also an overloaded function.
    * @param x - the number
+   *
+   * @defaultValue 123
    */
   // eslint-disable-next-line @typescript-eslint/explicit-member-accessibility
   exampleFunction(x: number): number;
@@ -316,6 +318,8 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter
 export interface IDocInterface5 {
   /**
    * Property of type string that does something
+   *
+   * @defaultValue "Hello World"
    */
   regularProperty: string;
 }

build-tests/api-documenter-test/src/test/__snapshots__/snapshot.test.ts.snap

@@ -349,6 +349,7 @@ methods:
     summary: This is also an overloaded function.
     remarks: ''
     example: []
+    defaultValue: '123'
     isPreview: false
     isDeprecated: false
     syntax:
@@ -885,6 +886,7 @@ properties:
     summary: Property of type string that does something
     remarks: ''
     example: []
+    defaultValue: '\\"Hello World\\"'
     isPreview: false
     isDeprecated: false
     syntax:
@@ -1800,6 +1802,10 @@ the number
 
 number
 
+## Default Value
+
+123
+
 ",
   "/api-documenter-test.docclass1.genericwithconstraintanddefault.md": "<!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
@@ -3452,6 +3458,11 @@ Property of type string that does something
 \`\`\`typescript
 regularProperty: string;
 \`\`\`
+
+## Default Value
+
+\\"Hello World\\"
+
 ",
   "/api-documenter-test.idocinterface6.arrayproperty.md": "<!-- Do not edit this file. It is automatically generated by API Documenter. -->
 

common/changes/@microsoft/api-documenter/fix-api-documenter-defaultvalue_2026-03-30-07-12.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Add support for @defaultValue in Markdown and Yaml documenters",
+      "type": "minor",
+      "packageName": "@microsoft/api-documenter"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "40660121+colinaaa@users.noreply.github.com"
+}