fix(openapi3): import nested description of properties

.chronus/changes/feat-tsp-openapi3-nested-description-2025-11-26-22-44-4.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/openapi3"
+---
+
+[converter] Import nested `description` of `properties`

packages/openapi3/src/cli/actions/convert/generators/generate-types.ts

@@ -10,6 +10,7 @@ import {
   getDecoratorsForSchema,
   normalizeObjectValueToTSValueExpression,
 } from "../utils/decorators.js";
+import { generateDocs } from "../utils/docs.js";
 import { getScopeAndName } from "../utils/get-scope-and-name.js";
 import { generateDecorators } from "./generate-decorators.js";
 
@@ -437,6 +438,9 @@ export class SchemaToExpressionGenerator {
     if (schema.properties) {
       for (const name of Object.keys(schema.properties)) {
         const originalPropSchema = schema.properties[name];
+        const description = schema.properties[name].description
+          ? generateDocs(schema.properties[name].description)
+          : "";
         const isEnumType = !!context && isReferencedEnumType(originalPropSchema, context);
         const isUnionType = !!context && isReferencedUnionType(originalPropSchema, context);
         const propType = this.generateTypeFromRefableSchema(originalPropSchema, callingScope);
@@ -449,7 +453,7 @@ export class SchemaToExpressionGenerator {
           .join("");
         const isOptional = !requiredProps.includes(name) ? "?" : "";
         props.push(
-          `${decorators}${printIdentifier(name)}${isOptional}: ${this.getPartType(propType, name, isHttpPart, encoding, isEnumType, isUnionType)}`,
+          `${description}${decorators}${printIdentifier(name)}${isOptional}: ${this.getPartType(propType, name, isHttpPart, encoding, isEnumType, isUnionType)}`,
         );
       }
     }

packages/openapi3/test/tsp-openapi3/nested-description.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { renderTypeSpecForOpenAPI3 } from "./utils/tsp-for-openapi3.js";
+
+describe("nested property descriptions", () => {
+  it("generates doc comments from nested property descriptions", async () => {
+    const tsp = await renderTypeSpecForOpenAPI3({
+      paths: {
+        "/": {
+          get: {
+            operationId: "extensive",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "The request has succeeded.",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/Dog",
+                    },
+                  },
+                },
+              },
+              "4XX": {
+                description: "Client error",
+              },
+              "5XX": {
+                description: "Server error",
+              },
+            },
+          },
+        },
+      },
+      schemas: {
+        Dog: {
+          properties: {
+            top_level: {
+              type: "object",
+              description: "This is a top level property description.",
+              properties: {
+                nested: {
+                  type: "object",
+                  description: "This is a nested property description.",
+                  properties: {
+                    deep_nested: {
+                      type: "string",
+                      description: "This is a deep nested property description.",
+                    },
+                  },
+                  required: ["deep_nested"],
+                },
+              },
+              required: ["nested"],
+            },
+            first_id: {
+              type: "string",
+              example: "msg_abc123",
+            },
+            last_id: {
+              type: "string",
+              example: "msg_abc123",
+            },
+            has_more: {
+              type: "boolean",
+              example: false,
+            },
+          },
+          required: ["first_id", "last_id", "top_level"],
+        },
+      },
+    });
+
+    expect(tsp).toMatchInlineSnapshot(`
+"import "@typespec/http";
+import "@typespec/openapi";
+import "@typespec/openapi3";
+
+using Http;
+using OpenAPI;
+
+@service(#{ title: "Test Service" })
+@info(#{ version: "1.0.0" })
+namespace TestService;
+
+model Dog {
+  /** This is a top level property description. */
+  top_level: {
+    /** This is a nested property description. */
+    nested: {
+      /** This is a deep nested property description. */
+      deep_nested: string;
+    };
+  };
+
+  first_id: string;
+  last_id: string;
+  has_more?: boolean;
+}
+
+@route("/") @get op extensive(): Dog | {
+  @statusCode
+  @minValue(400)
+  @maxValue(499)
+  statusCode: int32;
+} | {
+  @statusCode
+  @minValue(500)
+  @maxValue(599)
+  statusCode: int32;
+};
+"
+    `);
+  });
+});