add request and response examples

miguelgrinberg · miguelgrinberg · commit 9ae6a7c54d9f · 2025-03-13T17:52:49.000Z
diff --git a/src/Examples.tsx b/src/Examples.tsx
@@ -0,0 +1,22 @@
+import CollapsingDetails from './CollapsingDetails';
+import Details from './Details';
+import { Example } from './metamodel';
+
+type Props = {
+  examples: Record<string, Example>;
+};
+
+export default function Examples({ examples }: Props) {
+  return (
+    <CollapsingDetails header="Examples">
+      {Object.keys(examples).map(example => (
+        <CollapsingDetails header={example}>
+          {examples[example].summary && <Details header="Summary" value={examples[example].summary} />}
+          {examples[example].description && <Details header="Description" value={examples[example].description} />}
+          {examples[example].value && <Details header="Value" value={examples[example].value} />}
+          {examples[example].external_value && <Details header="External Value" value={examples[example].external_value} />}
+        </CollapsingDetails>
+      ))}
+    </CollapsingDetails>
+  );
+}
diff --git a/src/Request.tsx b/src/Request.tsx
@@ -5,6 +5,7 @@ import Properties from './Properties';
 import Body from './Body';
 import Behaviors from './Behaviors';
 import AttachedBehaviors from './AttachedBehaviors';
+import Examples from './Examples';
 
 import { Request as RequestType } from './metamodel';
 
@@ -28,6 +29,7 @@ export default function Request({ type }: Props) {
       <Body body={type.body} />
       {type.behaviors && <Behaviors behaviors={type.behaviors} />}
       {type.attachedBehaviors && <AttachedBehaviors behaviors={type.attachedBehaviors} />}
+      {type.examples && <Examples examples={type.examples} />}
     </>
   );
 }
diff --git a/src/Response.tsx b/src/Response.tsx
@@ -4,6 +4,7 @@ import Body from './Body';
 import Behaviors from './Behaviors';
 import Description from './Description';
 import AttachedBehaviors from './AttachedBehaviors';
+import Examples from './Examples';
 
 import { Response as ResponseType } from './metamodel';
 
@@ -34,6 +35,7 @@ export default function Response({ type }: Props) {
           ))}
         </CollapsingDetails>
       }
+      {type.examples && <Examples examples={type.examples} />}
     </>
   );
 }
diff --git a/src/metamodel.ts b/src/metamodel.ts
@@ -260,6 +260,23 @@ export class Interface extends BaseType {
   variants?: Container
 }
 
+/**
+ * The Example type is used for both requests and responses
+ * This type definition is taken from the OpenAPI spec
+ *     https://spec.openapis.org/oas/v3.1.0#example-object
+ * With the exception of using String as the 'value' type
+ */
+export class Example {
+  /** Short description. */
+  summary?: string
+  /** Long description. */
+  description?: string
+  /** Embedded literal example. Mutually exclusive with `external_value` */
+  value?: string
+  /** A URI that points to the literal example */
+  external_value?: string
+}
+
 /**
  * A request type
  */
@@ -288,6 +305,7 @@ export class Request extends BaseType {
   body: Body
   behaviors?: Behavior[]
   attachedBehaviors?: string[]
+  examples?: Record<string, Example>
 }
 
 /**
@@ -300,6 +318,7 @@ export class Response extends BaseType {
   behaviors?: Behavior[]
   attachedBehaviors?: string[]
   exceptions?: ResponseException[]
+  examples?: Record<string, Example>
 }
 
 export class ResponseException {

Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@ import Body from './Body';`
`4`	`4`	`import Behaviors from './Behaviors';`
`5`	`5`	`import Description from './Description';`
`6`	`6`	`import AttachedBehaviors from './AttachedBehaviors';`
	`7`	`+import Examples from './Examples';`
`7`	`8`
`8`	`9`	`import { Response as ResponseType } from './metamodel';`
`9`	`10`
`@@ -34,6 +35,7 @@ export default function Response({ type }: Props) {`
`34`	`35`	`))}`
`35`	`36`	`</CollapsingDetails>`
`36`	`37`	`}`
	`38`	`+ {type.examples && <Examples examples={type.examples} />}`
`37`	`39`	`</>`
`38`	`40`	`);`
`39`	`41`	`}`