From f4c8710673139b1d05cb77717f897b717efa1d7d Mon Sep 17 00:00:00 2001
From: Timothee Guerin <tiguerin@microsoft.com>
Date: Fri, 6 Sep 2024 16:45:59 -0700
Subject: [PATCH] Fix set response doc when an envelope (#4322)

fix [#3664](https://github.com/microsoft/typespec/issues/3664)
---
 ...-response-doc-envelope-2024-8-3-18-12-4.md |  8 +++++
 packages/http/src/responses.ts                | 30 +++++++++----------
 .../http/test/response-descriptions.test.ts   | 14 +++++++++
 .../@typespec/openapi3/openapi.yaml           |  2 +-
 4 files changed, 37 insertions(+), 17 deletions(-)
 create mode 100644 .chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md

diff --git a/.chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md b/.chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md
new file mode 100644
index 000000000..07a087958
--- /dev/null
+++ b/.chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md
@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: fix
+packages:
+  - "@typespec/http"
+---
+
+Use user provided description of model if model has a status code property(detect it as an response envelope)
diff --git a/packages/http/src/responses.ts b/packages/http/src/responses.ts
index feccf086f..8f29bdb07 100644
--- a/packages/http/src/responses.ts
+++ b/packages/http/src/responses.ts
@@ -19,13 +19,7 @@ import { HttpProperty } from "./http-property.js";
 import { HttpStateKeys, reportDiagnostic } from "./lib.js";
 import { Visibility } from "./metadata.js";
 import { resolveHttpPayload } from "./payload.js";
-import {
-  HttpOperationBody,
-  HttpOperationMultipartBody,
-  HttpOperationResponse,
-  HttpStatusCodes,
-  HttpStatusCodesEntry,
-} from "./types.js";
+import { HttpOperationResponse, HttpStatusCodes, HttpStatusCodesEntry } from "./types.js";
 
 /**
  * Get the responses for a given operation.
@@ -121,13 +115,7 @@ function processResponseType(
       statusCode: typeof statusCode === "object" ? "*" : (String(statusCode) as any),
       statusCodes: statusCode,
       type: responseType,
-      description: getResponseDescription(
-        program,
-        operation,
-        responseType,
-        statusCode,
-        resolvedBody
-      ),
+      description: getResponseDescription(program, operation, responseType, statusCode, metadata),
       responses: [],
     };
 
@@ -202,12 +190,22 @@ function getResponseHeaders(
   return responseHeaders;
 }
 
+function isResponseEnvelope(metadata: HttpProperty[]): boolean {
+  return metadata.some(
+    (prop) =>
+      prop.kind === "body" ||
+      prop.kind === "bodyRoot" ||
+      prop.kind === "multipartBody" ||
+      prop.kind === "statusCode"
+  );
+}
+
 function getResponseDescription(
   program: Program,
   operation: Operation,
   responseType: Type,
   statusCode: HttpStatusCodes[number],
-  body: HttpOperationBody | HttpOperationMultipartBody | undefined
+  metadata: HttpProperty[]
 ): string | undefined {
   // NOTE: If the response type is an envelope and not the same as the body
   // type, then use its @doc as the response description. However, if the
@@ -216,7 +214,7 @@ function getResponseDescription(
   // as the response description. This allows more freedom to change how
   // TypeSpec is expressed in semantically equivalent ways without causing
   // the output to change unnecessarily.
-  if (body === undefined || body.property) {
+  if (isResponseEnvelope(metadata)) {
     const desc = getDoc(program, responseType);
     if (desc) {
       return desc;
diff --git a/packages/http/test/response-descriptions.test.ts b/packages/http/test/response-descriptions.test.ts
index eae81c387..d60878209 100644
--- a/packages/http/test/response-descriptions.test.ts
+++ b/packages/http/test/response-descriptions.test.ts
@@ -66,4 +66,18 @@ describe("http: response descriptions", () => {
     strictEqual(op.responses[2].description, "Not found model");
     strictEqual(op.responses[3].description, "Generic error");
   });
+
+  it("@doc on response model set response doc if model is an evelope with @statusCode", async () => {
+    const op = await getHttpOp(
+      `
+      /** Explicit doc */
+      model Result {
+        @statusCode _: 201;
+        implicit: 200;
+      }
+      op read(): Result;
+      `
+    );
+    strictEqual(op.responses[0].description, "Explicit doc");
+  });
 });
diff --git a/packages/samples/test/output/documentation/@typespec/openapi3/openapi.yaml b/packages/samples/test/output/documentation/@typespec/openapi3/openapi.yaml
index 36f30e4ec..755b42d3d 100644
--- a/packages/samples/test/output/documentation/@typespec/openapi3/openapi.yaml
+++ b/packages/samples/test/output/documentation/@typespec/openapi3/openapi.yaml
@@ -73,7 +73,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Resp'
         '404':
-          description: The server cannot find the requested resource.
+          description: Not found
           content:
             application/json:
               schema: