feat: add dropdown/logic for multiple http response schemas (#3280)

sahil485 · web-flow · commit 44ed9ec0235a · 2025-07-25T09:38:53.000-04:00
diff --git a/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointContentCodeSnippets.tsx b/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointContentCodeSnippets.tsx
@@ -304,13 +304,21 @@ export const EndpointContentCodeSnippets = memo(
   UnmemoizedEndpointContentCodeSnippets
 );
 
-function renderResponseTitle(title: string, statusCode: number | string) {
+export function renderResponseTitle(
+  title: string,
+  statusCode: number | string,
+  hideTitle?: boolean
+) {
   return (
     <span className="inline-flex items-center gap-2">
       <StatusCodeBadge statusCode={statusCode} />
-      <span className={`text-intent-${statusCodeToIntent(String(statusCode))}`}>
-        {title}
-      </span>
+      {!hideTitle && (
+        <span
+          className={`text-intent-${statusCodeToIntent(String(statusCode))}`}
+        >
+          {title}
+        </span>
+      )}
     </span>
   );
 }
diff --git a/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointContentLeft.tsx b/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointContentLeft.tsx
@@ -13,6 +13,7 @@ import {
 } from "../type-definitions/TypeDefinitionContext";
 import { WithSeparator } from "../type-definitions/TypeDefinitionDetails";
 import { EndpointErrorGroup } from "./EndpointErrorGroup";
+import { EndpointMultipleResponseSection } from "./EndpointMultipleResponseSection";
 import {
   EndpointRequestSection,
   createEndpointRequestDescriptionFallback,
@@ -217,31 +218,39 @@ export async function EndpointContentLeft({
       </TypeDefinitionAnchorPart>
       <TypeDefinitionResponse>
         <TypeDefinitionAnchorPart part="response">
-          {endpoint.responses?.[0] != null && (
-            <EndpointSection
-              title="Response"
-              description={
-                <MdxServerComponentProseSuspense
-                  size="sm"
-                  className="text-(color:--grayscale-a11)"
-                  mdx={endpoint.responses[0].description}
-                  fallback={
-                    <ResponseSummaryFallback
-                      response={endpoint.responses[0]}
-                      types={types}
-                    />
-                  }
-                />
-              }
-            >
-              <TypeDefinitionAnchorPart part="body">
-                <EndpointResponseSection
-                  body={endpoint.responses[0].body}
-                  types={types}
-                />
-              </TypeDefinitionAnchorPart>
-            </EndpointSection>
-          )}
+          {endpoint.responses?.[0] != null ? (
+            endpoint.responses.length > 1 ? (
+              <EndpointMultipleResponseSection
+                method={endpoint.method}
+                responses={endpoint.responses}
+                types={types}
+              />
+            ) : (
+              <EndpointSection
+                title="Response"
+                description={
+                  <MdxServerComponentProseSuspense
+                    size="sm"
+                    className="text-(color:--grayscale-a11)"
+                    mdx={endpoint.responses[0].description}
+                    fallback={
+                      <ResponseSummaryFallback
+                        response={endpoint.responses[0]}
+                        types={types}
+                      />
+                    }
+                  />
+                }
+              >
+                <TypeDefinitionAnchorPart part="body">
+                  <EndpointResponseSection
+                    body={endpoint.responses[0].body}
+                    types={types}
+                  />
+                </TypeDefinitionAnchorPart>
+              </EndpointSection>
+            )
+          ) : null}
           {showErrors && endpoint.errors && endpoint.errors.length > 0 && (
             <TypeDefinitionAnchorPart part="error">
               <EndpointSection title="Errors" hideSeparator>
diff --git a/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointContext.tsx b/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointContext.tsx
@@ -7,6 +7,7 @@ import { noop } from "ts-essentials";
 import {
   EndpointDefinition,
   ErrorResponse,
+  HttpResponse,
   Protocol,
 } from "@fern-api/fdr-sdk/api-definition";
 import { useCurrentAnchor } from "@fern-docs/components/hooks/use-anchor";
@@ -18,11 +19,19 @@ export const EndpointContext = React.createContext<
   {
     selectedError: ErrorResponse | undefined;
     setSelectedError: (error: ErrorResponse | undefined) => void;
+    selectedResponse: HttpResponse | undefined;
+    setSelectedResponse: (response: HttpResponse | undefined) => void;
+    setSelectedResponseByStatusCode: (
+      statusCode: number | string | undefined
+    ) => void;
     endpointProtocol: Protocol | undefined;
   } & Omit<ReturnType<typeof useExampleSelection>, "defaultLanguage">
 >({
   selectedError: undefined,
   setSelectedError: noop,
+  selectedResponse: undefined,
+  setSelectedResponse: noop,
+  setSelectedResponseByStatusCode: noop,
   selectedExample: undefined,
   examplesByStatusCode: {},
   examplesByKeyAndStatusCode: {},
@@ -53,6 +62,30 @@ export function EndpointContextProvider({
     setSelectedExampleKey,
   } = useExampleSelection(endpoint);
 
+  const [selectedResponse, setSelectedResponse] = React.useState<
+    HttpResponse | undefined
+  >(endpoint.responses?.[0]);
+
+  const responseByStatusCode = React.useMemo(() => {
+    const map: Record<string, HttpResponse> = {};
+    endpoint.responses?.forEach((response) => {
+      map[String(response.statusCode)] = response;
+    });
+    return map;
+  }, [endpoint.responses]);
+
+  const setSelectedResponseByStatusCode = React.useCallback(
+    (statusCode: number | string | undefined) => {
+      if (statusCode != null) {
+        const response = responseByStatusCode[String(statusCode)];
+        if (response) {
+          setSelectedResponse(response);
+        }
+      }
+    },
+    [responseByStatusCode, setSelectedResponse]
+  );
+
   const setStatusCode = React.useCallback(
     (statusCode: number | string | undefined) => {
       setSelectedExampleKey((prev) => {
@@ -105,6 +138,9 @@ export function EndpointContextProvider({
     () => ({
       selectedError,
       setSelectedError: handleSelectError,
+      selectedResponse,
+      setSelectedResponse,
+      setSelectedResponseByStatusCode,
       selectedExample,
       examplesByStatusCode,
       examplesByKeyAndStatusCode,
@@ -116,6 +152,9 @@ export function EndpointContextProvider({
     [
       selectedError,
       handleSelectError,
+      selectedResponse,
+      setSelectedResponse,
+      setSelectedResponseByStatusCode,
       selectedExample,
       examplesByStatusCode,
       examplesByKeyAndStatusCode,
diff --git a/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointMultipleResponseSection.tsx b/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointMultipleResponseSection.tsx
@@ -0,0 +1,75 @@
+"use client";
+
+import React, { useCallback } from "react";
+
+import { ApiDefinition } from "@fern-api/fdr-sdk";
+import { HttpResponse } from "@fern-api/fdr-sdk/api-definition";
+
+import { MdxServerComponentProseSuspense } from "@/mdx/components/server-component";
+
+import { TypeDefinitionAnchorPart } from "../type-definitions/TypeDefinitionContext";
+import { renderResponseTitle } from "./EndpointContentCodeSnippets";
+import { useEndpointContext } from "./EndpointContext";
+import { EndpointResponseSection } from "./EndpointResponseSection";
+import { EndpointSection } from "./EndpointSection";
+import { ResponseSummaryFallback } from "./response-summary-fallback";
+
+export interface EndpointMultipleResponseSectionProps {
+  method: ApiDefinition.HttpMethod;
+  responses: HttpResponse[];
+  types: Record<string, ApiDefinition.TypeDefinition>;
+}
+
+export function EndpointMultipleResponseSection({
+  method,
+  responses,
+  types,
+}: EndpointMultipleResponseSectionProps) {
+  const { selectedResponse, setSelectedResponse, setSelectedExampleKey } =
+    useEndpointContext();
+
+  const getResponseId = useCallback(
+    (response: HttpResponse) => {
+      const title =
+        ApiDefinition.getMessageForStatus(response.statusCode, method) ??
+        "Response";
+
+      return renderResponseTitle(title, response.statusCode, true);
+    },
+    [method]
+  );
+
+  if (!selectedResponse) {
+    return null;
+  }
+
+  return (
+    <EndpointSection
+      title="Response"
+      description={
+        <MdxServerComponentProseSuspense
+          size="sm"
+          className="text-(color:--grayscale-a11)"
+          mdx={selectedResponse.description}
+          fallback={
+            <ResponseSummaryFallback
+              response={selectedResponse}
+              types={types}
+            />
+          }
+        />
+      }
+      multipleResponsesProps={{
+        responses,
+        selectedResponse,
+        setSelectedResponse,
+        getResponseId,
+        setSelectedExampleKey,
+      }}
+    >
+      <TypeDefinitionAnchorPart part="body">
+        <EndpointResponseSection body={selectedResponse.body} types={types} />
+      </TypeDefinitionAnchorPart>
+    </EndpointSection>
+  );
+}
diff --git a/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointSection.tsx b/packages/fern-docs/bundle/src/components/api-reference/endpoints/EndpointSection.tsx
@@ -1,27 +1,57 @@
-import React from "react";
+import React, { SetStateAction } from "react";
 
+import { RESET } from "jotai/utils";
+
+import { HttpResponse } from "@fern-api/fdr-sdk/api-definition";
 import { Separator } from "@fern-docs/components/Separator";
 
 import { ErrorBoundary } from "@/components/error-boundary";
 
+import { SelectedExampleKey } from "../type-definitions/EndpointContent";
+import { ResponseSelect } from "./MultipleResponsesSelect";
 import { SectionContainer, TypeDefinitionAnchor } from "./TypeDefinitionAnchor";
 
 export function EndpointSection({
   title,
   description,
   children,
   hideSeparator,
+  multipleResponsesProps,
 }: {
   title: React.ReactNode;
   description?: React.ReactNode;
   children: React.ReactNode;
   hideSeparator?: boolean;
+  multipleResponsesProps?: {
+    responses: HttpResponse[];
+    selectedResponse: HttpResponse;
+    setSelectedResponse: (response: HttpResponse) => void;
+    getResponseId: (response: HttpResponse) => React.JSX.Element;
+    setSelectedExampleKey: (
+      update: typeof RESET | SetStateAction<SelectedExampleKey>
+    ) => void;
+  };
 }) {
   return (
     <ErrorBoundary>
       <SectionContainer className="space-y-3">
         <TypeDefinitionAnchor>
-          <h3 className="mt-0">{title}</h3>
+          {multipleResponsesProps ? (
+            <div className="mt-0 flex flex-row items-center gap-2">
+              <h3 className="mb-0 mt-0">{title}</h3>
+              <ResponseSelect
+                responses={multipleResponsesProps.responses}
+                selectedResponse={multipleResponsesProps.selectedResponse}
+                setSelectedResponse={multipleResponsesProps.setSelectedResponse}
+                getResponseId={multipleResponsesProps.getResponseId}
+                setSelectedExampleKey={
+                  multipleResponsesProps.setSelectedExampleKey
+                }
+              />
+            </div>
+          ) : (
+            <h3 className="mt-0">{title}</h3>
+          )}
         </TypeDefinitionAnchor>
         {description}
         {hideSeparator ? null : <Separator />}
diff --git a/packages/fern-docs/bundle/src/components/api-reference/endpoints/ErrorExampleSelect.tsx b/packages/fern-docs/bundle/src/components/api-reference/endpoints/ErrorExampleSelect.tsx
@@ -15,6 +15,7 @@ import {
   ExamplesByStatusCode,
   StatusCode,
 } from "../type-definitions/EndpointContent";
+import { useEndpointContext } from "./EndpointContext";
 
 export declare namespace ErrorExampleSelect {
   export interface Props {
@@ -36,9 +37,12 @@ export const ErrorExampleSelect: FC<
   examplesByStatusCode,
   getExampleId,
 }) => {
+  const { setSelectedResponseByStatusCode } = useEndpointContext();
+
   const handleValueChange = (value: string) => {
     const [statusCode, responseIndex] = value.split(":");
     setSelectedExampleKey(String(statusCode ?? ""), Number(responseIndex ?? 0));
+    setSelectedResponseByStatusCode(statusCode ?? "");
   };
 
   const statusCode = selectedExample?.exampleCall.responseStatusCode;
diff --git a/packages/fern-docs/bundle/src/components/api-reference/endpoints/MultipleResponsesSelect.tsx b/packages/fern-docs/bundle/src/components/api-reference/endpoints/MultipleResponsesSelect.tsx
