feat: show custom status code field in API docs (#833)

packages/ui/app/src/api-page/endpoints/EndpointContentCodeSnippets.tsx

@@ -8,6 +8,7 @@ import { CodeSnippetExample } from "../examples/CodeSnippetExample";
 import { JsonPropertyPath } from "../examples/JsonPropertyPath";
 import type { CodeExample, CodeExampleGroup } from "../examples/code-example";
 import { lineNumberOf } from "../examples/utils";
+import { getSuccessMessageForStatus } from "../utils/getSuccessMessageForStatus";
 import { CodeExampleClientDropdown } from "./CodeExampleClientDropdown";
 import { EndpointUrlWithOverflow } from "./EndpointUrlWithOverflow";
 import { ErrorCodeSnippetExample } from "./ErrorCodeSnippetExample";
@@ -110,11 +111,24 @@ const UnmemoizedEndpointContentCodeSnippets: React.FC<EndpointContentCodeSnippet
                 }
             />
             {endpoint.responseBody?.shape.type === "fileDownload" && <AudioExample title="Response" />}
+
             {example.responseBody != null &&
                 endpoint.responseBody?.shape.type !== "fileDownload" &&
                 (selectedError == null ? (
                     <CodeSnippetExample
-                        title={"Response"}
+                        title={
+                            <div className="text-sm px-1 t-muted">
+                                Response -{" "}
+                                <span className="text-intent-success">
+                                    {endpoint.responseBody?.statusCode +
+                                        " " +
+                                        getSuccessMessageForStatus(
+                                            endpoint.responseBody?.statusCode as number,
+                                            endpoint.method,
+                                        )}
+                                </span>
+                            </div>
+                        }
                         onClick={(e) => {
                             e.stopPropagation();
                         }}

packages/ui/app/src/api-page/utils/getSuccessMessageForStatus.ts

@@ -0,0 +1,51 @@
+type StatusCodeMessages = {
+    [method: string]: string;
+};
+
+type SuccessMessages = {
+    [code: number]: StatusCodeMessages;
+};
+
+export const COMMON_SUCCESS_NAMES: SuccessMessages = {
+    200: {
+        PUT: "Updated",
+        DELETE: "Deleted",
+        default: "Success",
+    },
+    201: {
+        PUT: "Updated",
+        default: "Created",
+    },
+    202: {
+        default: "Accepted",
+    },
+    203: {
+        default: "Non-Authoritative Information",
+    },
+    204: {
+        default: "No Content",
+    },
+    205: {
+        default: "Reset Content",
+    },
+    206: {
+        default: "Partial Content",
+    },
+    207: {
+        default: "Multi-Status",
+    },
+    208: {
+        default: "Already Reported",
+    },
+    226: {
+        default: "IM Used",
+    },
+};
+
+export function getSuccessMessageForStatus(statusCode: number, method: string): string {
+    const messages = COMMON_SUCCESS_NAMES[statusCode];
+    if (!messages) {
+        return "Success";
+    }
+    return messages[method] ?? messages.default;
+}

packages/ui/app/src/resolver/ApiDefinitionResolver.ts

@@ -414,7 +414,7 @@ export class ApiDefinitionResolver {
             this.resolveResponseBodyShape(response.type),
             maybeSerializeMdxContent(response.description),
         ]);
-        return { shape, description, availability: undefined };
+        return { shape, description, statusCode: response?.statusCode ?? 200, availability: undefined };
     }
 
     // HACKHACK: this handles the case where FernIR is unable to interpret the security scheme for AsyncAPI

packages/ui/app/src/resolver/__test__/__snapshots__/ApiDefinitionResolver.test.ts.snap

@@ -47,6 +47,7 @@ exports[`resolveApiDefinition > should finish resolving 1`] = `
               },
               "type": "list",
             },
+            "statusCode": 200,
           },
           "slug": [
             "merchants",

packages/ui/app/src/resolver/types.ts

@@ -348,6 +348,7 @@ export interface ResolvedObjectProperty extends WithMetadata {
 
 export interface ResolvedResponseBody extends WithMetadata {
     shape: ResolvedHttpResponseBodyShape;
+    statusCode: number;
 }
 
 export type ResolvedEndpointPathParts = ResolvedEndpointPathParts.Literal | ResolvedEndpointPathParts.PathParameter;