OpenAPI: Display Response in a separate section

.changeset/spotty-worlds-shop.md

@@ -0,0 +1,5 @@
+---
+'fumadocs-openapi': minor
+---
+
+Display Response in a separate section

packages/openapi/src/render/codeblock.tsx

@@ -2,26 +2,26 @@ import { type HTMLAttributes } from 'react';
 import * as Base from 'fumadocs-ui/components/codeblock';
 import type { RenderContext } from '@/types';
 import { highlight } from 'fumadocs-core/highlight';
+import { cn } from 'fumadocs-ui/utils/cn';
 
-export type CodeBlockProps = HTMLAttributes<HTMLPreElement> & {
+export interface CodeBlockProps extends HTMLAttributes<HTMLElement> {
   code: string;
   lang: string;
   ctx: RenderContext;
-};
+}
 
-export async function CodeBlock({
-  code,
-  lang,
-  ctx,
-  ...rest
-}: CodeBlockProps): Promise<React.ReactElement> {
+export async function CodeBlock({ code, lang, ctx, ...rest }: CodeBlockProps) {
   const rendered = await highlight(code, {
     lang,
     ...ctx.shikiOptions,
     components: {
-      pre: (props) => <Base.Pre {...props} {...rest} />,
+      pre: (props) => <Base.Pre {...props} />,
     },
   });
 
-  return <Base.CodeBlock className="my-0">{rendered}</Base.CodeBlock>;
+  return (
+    <Base.CodeBlock className={cn('my-0', rest.className)}>
+      {rendered}
+    </Base.CodeBlock>
+  );
 }

packages/openapi/src/render/operation/api-example.tsx

@@ -2,7 +2,6 @@ import type { MethodInformation, RenderContext } from '@/types';
 import { type ReactNode } from 'react';
 import { Markdown } from '@/render/markdown';
 import { type CodeSample } from '@/render/operation/index';
-import { getTypescriptSchema } from '@/utils/get-typescript-schema';
 import { CodeBlock } from '@/render/codeblock';
 import {
   CodeExample,
@@ -177,50 +176,26 @@ function ResponseTabs({
   operation: NoReference<MethodInformation>;
   ctx: RenderContext;
 }) {
-  const { renderer, generateTypeScriptSchema, schema } = ctx;
+  const { renderer } = ctx;
   if (!operation.responses) return null;
 
   async function renderResponse(code: string) {
-    const response =
-      operation.responses && code in operation.responses
-        ? operation.responses[code]
-        : null;
-
-    const media = getPreferredType(response?.content ?? {});
+    const response = operation.responses?.[code];
+    const media = response?.content ? getPreferredType(response.content) : null;
     const responseOfType = media ? response?.content?.[media] : null;
 
-    const description =
-      operation.responses?.[code].description ??
-      responseOfType?.schema?.description ??
-      '';
-
-    let ts: string | undefined;
-    if (generateTypeScriptSchema) {
-      ts = await generateTypeScriptSchema(operation, code);
-    } else if (
-      generateTypeScriptSchema === undefined &&
-      responseOfType?.schema
-    ) {
-      ts = await getTypescriptSchema(
-        responseOfType?.schema,
-        schema.dereferenceMap,
-      );
-    }
-
-    const values: string[] = [];
-    let exampleSlot: ReactNode;
-
+    let slot: ReactNode = 'Empty';
     if (responseOfType?.examples) {
-      exampleSlot = Object.entries(responseOfType.examples).map(
-        ([key, sample], i) => {
-          const title = sample?.summary ?? `Example ${i + 1}`;
+      const values: string[] = [];
+
+      const children = Object.entries(responseOfType.examples).map(
+        ([key, sample]) => {
+          const title = sample?.summary ?? `Example ${key}`;
 
           values.push(title);
           return (
             <renderer.ResponseType key={key} label={title}>
-              {sample?.description ? (
-                <Markdown text={sample.description} />
-              ) : null}
+              {sample?.description && <Markdown text={sample.description} />}
               <CodeBlock
                 lang="json"
                 code={JSON.stringify(sample.value, null, 2)}
@@ -230,39 +205,27 @@ function ResponseTabs({
           );
         },
       );
-    } else if (responseOfType?.example || responseOfType?.schema) {
-      values.push('Response');
 
-      exampleSlot = (
-        <renderer.ResponseType label="Response">
-          <CodeBlock
-            lang="json"
-            code={JSON.stringify(
-              responseOfType.example ?? sample(responseOfType.schema as object),
-              null,
-              2,
-            )}
-            ctx={ctx}
-          />
-        </renderer.ResponseType>
+      slot = (
+        <renderer.ResponseTypes defaultValue={values[0]}>
+          {children}
+        </renderer.ResponseTypes>
+      );
+    } else if (responseOfType?.example || responseOfType?.schema) {
+      slot = (
+        <CodeBlock
+          lang="json"
+          code={JSON.stringify(
+            responseOfType.example ?? sample(responseOfType.schema as object),
+            null,
+            2,
+          )}
+          ctx={ctx}
+        />
       );
     }
 
-    return (
-      <renderer.Response value={code}>
-        {description ? <Markdown text={description} /> : null}
-        {exampleSlot ? (
-          <renderer.ResponseTypes defaultValue={values[0]}>
-            {exampleSlot}
-            {ts ? (
-              <renderer.ResponseType label="TypeScript">
-                <CodeBlock lang="ts" code={ts} ctx={ctx} />
-              </renderer.ResponseType>
-            ) : null}
-          </renderer.ResponseTypes>
-        ) : null}
-      </renderer.Response>
-    );
+    return <renderer.Response value={code}>{slot}</renderer.Response>;
   }
 
   const codes = Object.keys(operation.responses);

packages/openapi/src/render/operation/index.tsx

@@ -20,8 +20,10 @@ import {
   getAPIExamples,
 } from '@/render/operation/api-example';
 import { MethodLabel } from '@/ui/components/method-label';
-
-import { RequestData, supportedMediaTypes } from '@/requests/_shared';
+import { type RequestData, supportedMediaTypes } from '@/requests/_shared';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { CodeBlock } from '@/render/codeblock';
+import { getTypescriptSchema } from '@/utils/get-typescript-schema';
 
 export interface CodeSample {
   lang: string;
@@ -110,38 +112,27 @@ export function Operation({
     );
   }
 
-  if (method.responses && ctx.showResponseSchema) {
+  if (method.responses && ctx.showResponseSchema !== false) {
+    const statuses = Object.keys(method.responses);
+
     responseNode = (
       <>
         {heading(headingLevel, 'Response Body', ctx)}
 
-        {Object.entries(method.responses).map(([status, response]) => {
-          if (!response.content) return;
-
-          const mediaType = getPreferredType(response.content);
-          if (!mediaType) return null;
-
-          const content = response.content[mediaType];
-          if (!content.schema) return null;
-
-          return (
-            <Fragment key={status}>
-              {heading(headingLevel + 1, status, ctx)}
-              <Markdown text={response.description} />
-
-              <Schema
-                name="response"
-                schema={content.schema}
-                ctx={{
-                  render: ctx,
-                  writeOnly: false,
-                  readOnly: true,
-                  required: true,
-                }}
-              />
-            </Fragment>
-          );
-        })}
+        <Tabs
+          items={statuses}
+          groupId="fumadocs_openapi_responses"
+          className="bg-transparent"
+        >
+          {statuses.map((status) => (
+            <ResponseTab
+              key={status}
+              status={status}
+              operation={method}
+              ctx={ctx}
+            />
+          ))}
+        </Tabs>
       </>
     );
   }
@@ -244,6 +235,57 @@ export function Operation({
   }
 }
 
+async function ResponseTab({
+  status,
+  operation,
+  ctx,
+}: {
+  status: string;
+  operation: MethodInformation;
+  ctx: RenderContext;
+}) {
+  const response = operation.responses![status];
+  const { generateTypeScriptSchema, schema } = ctx;
+  const mediaType = response.content
+    ? getPreferredType(response.content)
+    : null;
+  const responseOfType = mediaType ? response.content?.[mediaType] : null;
+
+  const description =
+    responseOfType?.schema?.description ?? response.description ?? '';
+
+  let ts: string | undefined;
+  if (generateTypeScriptSchema) {
+    ts = await generateTypeScriptSchema(operation, status);
+  } else if (generateTypeScriptSchema === undefined && responseOfType?.schema) {
+    ts = await getTypescriptSchema(
+      responseOfType?.schema,
+      schema.dereferenceMap,
+    );
+  }
+
+  return (
+    <Tab value={status}>
+      <Markdown text={description} />
+
+      {responseOfType?.schema && (
+        <Schema
+          name="response"
+          schema={responseOfType.schema}
+          ctx={{
+            render: ctx,
+            writeOnly: false,
+            readOnly: true,
+            required: true,
+          }}
+        />
+      )}
+
+      {ts && <CodeBlock lang="ts" code={ts} ctx={ctx} className="mt-4" />}
+    </Tab>
+  );
+}
+
 function WebhookCallback({
   callback,
   ctx,

packages/openapi/src/render/renderer.tsx

@@ -3,11 +3,11 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
 import {
   API,
-  Root,
-  APIInfo,
   APIExample,
-  Property,
+  APIInfo,
   ObjectCollapsible,
+  Property,
+  Root,
 } from '@/ui';
 import type { RenderContext, ServerObject } from '@/types';
 import { APIPlayground, type APIPlaygroundProps } from '@/playground';
@@ -110,7 +110,9 @@ export function createRenders(
       </APIInfo>
     ),
     APIExample,
-    Responses: Tabs,
+    Responses: (props) => (
+      <Tabs {...props} groupId="fumadocs_openapi_responses" />
+    ),
     Response: Tab,
     ResponseTypes: (props) => (
       <Accordions

packages/openapi/src/types.ts

@@ -82,6 +82,8 @@ export interface RenderContext {
 
   /**
    * Show full response schema instead of only example response & Typescript definitions
+   *
+   * @default true
    */
   showResponseSchema?: boolean;
 }