Support externalDocs on properties (#3558)

fix #3509 

Same pr for openapi3 microsoft/typespec#9076

Author: timotheeguerin

.chronus/changes/external-docs-properties-2025-10-24-13-31-13.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@azure-tools/typespec-autorest"
+---
+
+Respect `@externalDocs` on properties

packages/typespec-autorest/src/openapi.ts

@@ -153,6 +153,7 @@ import { createDiagnostic, reportDiagnostic } from "./lib.js";
 import {
   OpenAPI2BodyParameter,
   OpenAPI2Document,
+  OpenAPI2ExternalDocs,
   OpenAPI2FileSchema,
   OpenAPI2HeaderDefinition,
   OpenAPI2HeaderParameter,
@@ -2040,7 +2041,7 @@ export async function getOpenAPIForService(
       if (prop.defaultValue && !("$ref" in property)) {
         property.default = getDefaultValue(prop.defaultValue, prop);
       }
-
+      applyExternalDocs(prop, property);
       if (isReadonlyProperty(program, prop)) {
         property.readOnly = true;
       } else {
@@ -2458,7 +2459,7 @@ export async function getOpenAPIForService(
       target.title = summary;
     }
   }
-  function applyExternalDocs(typespecType: Type, target: Record<string, unknown>) {
+  function applyExternalDocs(typespecType: Type, target: { externalDocs?: OpenAPI2ExternalDocs }) {
     const externalDocs = getExternalDocs(program, typespecType);
     if (externalDocs) {
       target.externalDocs = externalDocs;

packages/typespec-autorest/src/openapi2-document.ts

@@ -112,7 +112,7 @@ export type JsonType = "array" | "boolean" | "integer" | "number" | "object" | "
 export type OpenAPI2SchemaRefProperty = Ref<OpenAPI2Schema> &
   Pick<
     OpenAPI2Schema,
-    "readOnly" | "description" | "default" | "x-ms-mutability" | "title" | "xml"
+    "readOnly" | "description" | "default" | "x-ms-mutability" | "title" | "xml" | "externalDocs"
   > & {
     /**
      * Provide a different name to be used in the client.
@@ -291,6 +291,9 @@ export type OpenAPI2Schema = Extensions & {
    * XML metadata for the schema, if applicable.
    */
   xml?: XmlObject;
+
+  /** Additional external documentation. */
+  externalDocs?: OpenAPI2ExternalDocs;
 };
 
 export interface XmlObject {

packages/typespec-autorest/test/documentation.test.ts

@@ -1,41 +1,69 @@
 import { deepStrictEqual, strictEqual } from "assert";
-import { describe, it } from "vitest";
+import { expect, it } from "vitest";
 import { openApiFor } from "./test-host.js";
 
-describe("typespec-autorest: documentation", () => {
-  it("supports summary and description", async () => {
-    const openApi = await openApiFor(`
-        @summary("This is a summary")
-        @doc("This is the longer description")
-        op read(): {};
-      `);
-    strictEqual(openApi.paths["/"].get.summary, "This is a summary");
-    strictEqual(openApi.paths["/"].get.description, "This is the longer description");
+it("supports summary and description", async () => {
+  const openApi = await openApiFor(`
+      @summary("This is a summary")
+      @doc("This is the longer description")
+      op read(): {};
+    `);
+  strictEqual(openApi.paths["/"].get.summary, "This is a summary");
+  strictEqual(openApi.paths["/"].get.description, "This is the longer description");
+});
+
+it("supports externalDocs on operation", async () => {
+  const openApi = await openApiFor(`
+      @externalDocs("https://example.com", "more info")
+      op read(): {};
+    `);
+  deepStrictEqual(openApi.paths["/"].get.externalDocs, {
+    url: "https://example.com",
+    description: "more info",
   });
+});
+
+it("supports externalDocs on models", async () => {
+  const openApi = await openApiFor(`
+    @externalDocs("https://example.com", "more info")
+    model Foo {
+      name: string;
+    }
+    `);
+  deepStrictEqual(openApi.definitions.Foo.externalDocs, {
+    url: "https://example.com",
+    description: "more info",
+  });
+});
 
-  it("supports externalDocs on operation", async () => {
-    const openApi = await openApiFor(`
+it("supports externalDocs on properties", async () => {
+  const openApi = await openApiFor(`
+      model Foo {
         @externalDocs("https://example.com", "more info")
-        op read(): {};
+        name: string;
+      }
       `);
-    deepStrictEqual(openApi.paths["/"].get.externalDocs, {
+  expect(openApi.definitions.Foo.properties.name).toEqual({
+    type: "string",
+    externalDocs: {
       url: "https://example.com",
       description: "more info",
-    });
+    },
   });
-
-  it("supports externalDocs on models", async () => {
-    const openApi = await openApiFor(`
-      op read(): Foo;
-      
-      @externalDocs("https://example.com", "more info")
+});
+it("supports externalDocs on properties resulting in a $ref", async () => {
+  const openApi = await openApiFor(`
       model Foo {
-        name: string;
+        @externalDocs("https://example.com", "more info")
+        name: Bar;
       }
+      model Bar {}
       `);
-    deepStrictEqual(openApi.definitions.Foo.externalDocs, {
+  expect(openApi.definitions.Foo.properties.name).toEqual({
+    $ref: "#/definitions/Bar",
+    externalDocs: {
       url: "https://example.com",
       description: "more info",
-    });
+    },
   });
 });