feat(open-api): allow examples on OAS body and responses (#454)

Co-authored-by: Youssef Gaber <1728215+Gabrola@users.noreply.github.com>

Author: kkolstad

apps/docs/docs/open-api.mdx

@@ -64,6 +64,16 @@ export const contract = c.router({
         .openapi({
           title: 'User',
           description: 'A user schema',
+          mediaExamples: {
+            myExample: {
+              value: {
+                id: '123e4567-e89b-12d3-a456-426614174000',
+                name: 'John Doe',
+                phoneNumber: '555-555-5555',
+              },
+              summary: 'Example of a user',
+            },
+          },
         }),
     },
   },
@@ -76,6 +86,13 @@ See the [official `@anatine/zod-openapi` docs](https://www.npmjs.com/package/@an
 All Zod schemas defined in your contract can benefit from the additional OpenAPI schema, including `pathParams`, `queryParams`, and `responses`. These keys are all used when generating the OpenAPI JSON file. This could improve the quality of your generated documentation.
 :::
 
+### Adding Examples to the Media Type
+
+In order to add examples to the media type rather than to the schema itself (this is useful if you want to show multiple examples), we have added a `mediaExamples` property to the `.openapi()` method options.
+This will only work for the schemas of the body, responses and individual query parameters if you are using `jsonQuery` option.
+
+You can see an example of its usage in the code snippet above.
+
 ## Serving a Swagger UI
 
 In Express use `swagger-ui-express`:

libs/ts-rest/open-api/src/lib/ts-rest-open-api.spec.ts

@@ -1,6 +1,7 @@
 import { initContract } from '@ts-rest/core';
 import { z } from 'zod';
 import { generateOpenApi } from './ts-rest-open-api';
+import { extendApi } from '@anatine/zod-openapi';
 
 const c = initContract();
 
@@ -101,6 +102,35 @@ const router = c.router({
       200: c.type<{ message: string }>(),
     },
   },
+  mediaExamples: {
+    method: 'POST',
+    path: '/media-examples',
+    query: z.object({
+      foo: extendApi(z.string(), {
+        // this will only be added when jsonQuery is enabled
+        mediaExamples: {
+          one: { value: 'foo' },
+          two: { value: 'bar' },
+        },
+      }),
+    }),
+    summary: 'Examples API',
+    description: `Check that examples can be added to body and response types`,
+    body: extendApi(z.object({ id: z.string() }), {
+      mediaExamples: {
+        one: { value: { id: 'foo' } },
+        two: { value: { id: 'bar' } },
+      },
+    }),
+    responses: {
+      200: extendApi(z.object({ id: z.string() }), {
+        mediaExamples: {
+          three: { value: { id: 'foo' } },
+          four: { value: { id: 'bar' } },
+        },
+      }),
+    },
+  },
 });
 
 const expectedApiDoc = {
@@ -124,6 +154,66 @@ const expectedApiDoc = {
         tags: [],
       },
     },
+    '/media-examples': {
+      post: {
+        deprecated: undefined,
+        description: `Check that examples can be added to body and response types`,
+        parameters: [
+          {
+            in: 'query',
+            name: 'foo',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+          },
+        ],
+        requestBody: {
+          description: 'Body',
+          content: {
+            'application/json': {
+              schema: {
+                properties: {
+                  id: {
+                    type: 'string',
+                  },
+                },
+                required: ['id'],
+                type: 'object',
+              },
+              examples: {
+                one: { value: { id: 'foo' } },
+                two: { value: { id: 'bar' } },
+              },
+            },
+          },
+        },
+        responses: {
+          '200': {
+            content: {
+              'application/json': {
+                examples: {
+                  three: { value: { id: 'foo' } },
+                  four: { value: { id: 'bar' } },
+                },
+                schema: {
+                  properties: {
+                    id: {
+                      type: 'string',
+                    },
+                  },
+                  required: ['id'],
+                  type: 'object',
+                },
+              },
+            },
+            description: `200`,
+          },
+        },
+        summary: 'Examples API',
+        tags: [],
+      },
+    },
     '/posts': {
       get: {
         deprecated: undefined,
@@ -420,6 +510,12 @@ describe('ts-rest-open-api', () => {
               operationId: 'health',
             },
           },
+          '/media-examples': {
+            post: {
+              ...expectedApiDoc.paths['/media-examples'].post,
+              operationId: 'mediaExamples',
+            },
+          },
           '/posts': {
             get: {
               ...expectedApiDoc.paths['/posts'].get,
@@ -471,6 +567,34 @@ describe('ts-rest-open-api', () => {
         ...expectedApiDoc,
         paths: {
           ...expectedApiDoc.paths,
+          '/media-examples': {
+            ...expectedApiDoc.paths['/media-examples'],
+            post: {
+              ...expectedApiDoc.paths['/media-examples'].post,
+              parameters: [
+                {
+                  content: {
+                    'application/json': {
+                      examples: {
+                        one: {
+                          value: 'foo',
+                        },
+                        two: {
+                          value: 'bar',
+                        },
+                      },
+                      schema: {
+                        type: 'string',
+                      },
+                    },
+                  },
+                  in: 'query',
+                  name: 'foo',
+                  required: true,
+                },
+              ],
+            },
+          },
           '/posts': {
             ...expectedApiDoc.paths['/posts'],
             get: {

libs/ts-rest/open-api/src/lib/ts-rest-open-api.ts

@@ -7,10 +7,13 @@ import {
   isZodType,
 } from '@ts-rest/core';
 import {
+  ExamplesObject,
   InfoObject,
+  MediaTypeObject,
   OpenAPIObject,
   OperationObject,
   PathsObject,
+  SchemaObject,
 } from 'openapi3-ts';
 import { generateSchema } from '@anatine/zod-openapi';
 import { z } from 'zod';
@@ -129,7 +132,11 @@ const getQueryParametersFromZod = (zodObject: unknown, jsonQuery = false) => {
   const zodShape = extractZodObjectShape(zodObject);
 
   return Object.entries(zodShape).map(([key, value]) => {
-    const { description, ...schema } = getOpenApiSchemaFromZod(value)!;
+    const {
+      description,
+      mediaExamples: examples,
+      ...schema
+    } = getOpenApiSchemaFromZod(value)!;
     const isObject = (obj: z.ZodTypeAny) => {
       while (obj._def.innerType) {
         obj = obj._def.innerType;
@@ -149,6 +156,7 @@ const getQueryParametersFromZod = (zodObject: unknown, jsonQuery = false) => {
             content: {
               'application/json': {
                 schema: schema,
+                ...(examples && { examples }),
               },
             },
           }
@@ -162,6 +170,23 @@ const getQueryParametersFromZod = (zodObject: unknown, jsonQuery = false) => {
   });
 };
 
+declare module 'openapi3-ts' {
+  interface SchemaObject {
+    mediaExamples?: ExamplesObject;
+  }
+}
+
+const convertSchemaObjectToMediaTypeObject = (
+  input: SchemaObject,
+): MediaTypeObject => {
+  const { mediaExamples: examples, ...schema } = input;
+
+  return {
+    schema,
+    ...(examples && { examples }),
+  };
+};
+
 /**
  *
  * @param options.jsonQuery - Enable JSON query parameters, [see](/docs/open-api#json-query-params)
@@ -224,7 +249,7 @@ export const generateOpenApi = (
             ? {
                 content: {
                   'application/json': {
-                    schema: responseSchema,
+                    ...convertSchemaObjectToMediaTypeObject(responseSchema),
                   },
                 },
               }
@@ -251,7 +276,7 @@ export const generateOpenApi = (
               description: 'Body',
               content: {
                 [contentType]: {
-                  schema: bodySchema,
+                  ...convertSchemaObjectToMediaTypeObject(bodySchema),
                 },
               },
             },