Fix set response doc when an envelope (#4322)

fix [#3664](https://github.com/microsoft/typespec/issues/3664)

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

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;

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");
+  });
 });

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: