Grouping schemas by title and referencing them on @ts-rest/openapi (#727)

Co-authored-by: Oliver Butler <dev@oliverbutler.uk>

Author: nokutu

.changeset/twenty-fans-reflect.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/open-api': minor
+---
+
+Support automatic reusable "Components" in OpenAPI schemas, reduces final size of schema, uses the "Title" property from @anatine/zod-openapi

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

@@ -1096,5 +1096,210 @@ describe('ts-rest-open-api', () => {
         },
       });
     });
+
+    it('should extract references by title', () => {
+      const entity = extendApi(
+        z.object({
+          file: z.string(),
+        }),
+        {
+          title: 'Body',
+        },
+      );
+      const routerWithTransform = c.router({
+        formEndpoint: {
+          method: 'PUT',
+          path: '/title',
+          body: entity,
+          responses: {
+            200: entity,
+          },
+        },
+      });
+
+      const schema = generateOpenApi(routerWithTransform, {
+        info: { title: 'Title API', version: '0.1' },
+      });
+
+      expect(schema).toEqual({
+        components: {
+          schemas: {
+            Body: {
+              properties: {
+                file: {
+                  type: 'string',
+                },
+              },
+              required: ['file'],
+              title: 'Body',
+              type: 'object',
+            },
+          },
+        },
+        info: {
+          title: 'Title API',
+          version: '0.1',
+        },
+        openapi: '3.0.2',
+        paths: {
+          '/title': {
+            put: {
+              parameters: [],
+              requestBody: {
+                content: {
+                  'application/json': {
+                    schema: {
+                      $ref: '#/components/schemas/Body',
+                    },
+                  },
+                },
+                description: 'Body',
+              },
+              responses: {
+                '200': {
+                  content: {
+                    'application/json': {
+                      schema: {
+                        $ref: '#/components/schemas/Body',
+                      },
+                    },
+                  },
+                  description: '200',
+                },
+              },
+              tags: [],
+            },
+          },
+        },
+      });
+    });
+
+    it('should extract nested references by title', () => {
+      const child = extendApi(
+        z.object({
+          file: z.string(),
+        }),
+        {
+          title: 'Child',
+        },
+      );
+      const parent = extendApi(
+        z.object({
+          child: child,
+        }),
+        {
+          title: 'Parent',
+        },
+      );
+      const routerWithTransform = c.router({
+        formEndpoint: {
+          method: 'PUT',
+          path: '/title',
+          body: child,
+          responses: {
+            200: parent,
+          },
+        },
+      });
+
+      const schema = generateOpenApi(routerWithTransform, {
+        info: { title: 'Title API', version: '0.1' },
+      });
+
+      expect(schema).toEqual({
+        components: {
+          schemas: {
+            Child: {
+              properties: {
+                file: {
+                  type: 'string',
+                },
+              },
+              required: ['file'],
+              title: 'Child',
+              type: 'object',
+            },
+            Parent: {
+              properties: {
+                child: {
+                  $ref: '#/components/schemas/Child',
+                },
+              },
+              required: ['child'],
+              title: 'Parent',
+              type: 'object',
+            },
+          },
+        },
+        info: {
+          title: 'Title API',
+          version: '0.1',
+        },
+        openapi: '3.0.2',
+        paths: {
+          '/title': {
+            put: {
+              parameters: [],
+              requestBody: {
+                content: {
+                  'application/json': {
+                    schema: {
+                      $ref: '#/components/schemas/Child',
+                    },
+                  },
+                },
+                description: 'Body',
+              },
+              responses: {
+                '200': {
+                  content: {
+                    'application/json': {
+                      schema: {
+                        $ref: '#/components/schemas/Parent',
+                      },
+                    },
+                  },
+                  description: '200',
+                },
+              },
+              tags: [],
+            },
+          },
+        },
+      });
+    });
+
+    it('should throw if duplicated title', () => {
+      const routerWithTransform = c.router({
+        formEndpoint: {
+          method: 'PUT',
+          path: '/title',
+          body: extendApi(
+            z.object({
+              file: z.string(),
+            }),
+            {
+              title: 'Body',
+            },
+          ),
+          responses: {
+            200: extendApi(
+              z.object({
+                otherFile: z.string(),
+              }),
+              {
+                title: 'Body',
+              },
+            ),
+          },
+        },
+      });
+
+      expect(() =>
+        generateOpenApi(routerWithTransform, {
+          info: { title: 'Title API', version: '0.1' },
+        }),
+      ).toThrowError(/already exists with a different schema/);
+    });
   });
 });

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

@@ -13,6 +13,7 @@ import {
   OpenAPIObject,
   OperationObject,
   PathsObject,
+  ReferenceObject,
   SchemaObject,
 } from 'openapi3-ts';
 import { generateSchema } from '@anatine/zod-openapi';
@@ -187,6 +188,85 @@ const convertSchemaObjectToMediaTypeObject = (
   };
 };
 
+const extractReferenceSchemas = (
+  schema: SchemaObject,
+  referenceSchemas: { [id: string]: SchemaObject },
+): SchemaObject => {
+  if (schema.allOf) {
+    schema.allOf = schema.allOf?.map((subSchema) =>
+      extractReferenceSchemas(subSchema, referenceSchemas),
+    );
+  }
+
+  if (schema.anyOf) {
+    schema.anyOf = schema.anyOf?.map((subSchema) =>
+      extractReferenceSchemas(subSchema, referenceSchemas),
+    );
+  }
+
+  if (schema.oneOf) {
+    schema.oneOf = schema.oneOf?.map((subSchema) =>
+      extractReferenceSchemas(subSchema, referenceSchemas),
+    );
+  }
+
+  if (schema.not) {
+    schema.not = extractReferenceSchemas(schema.not, referenceSchemas);
+  }
+
+  if (schema.items) {
+    schema.items = extractReferenceSchemas(schema.items, referenceSchemas);
+  }
+
+  if (schema.properties) {
+    schema.properties = Object.entries(schema.properties).reduce<{
+      [p: string]: SchemaObject | ReferenceObject;
+    }>((prev, [propertyName, schema]) => {
+      prev[propertyName] = extractReferenceSchemas(schema, referenceSchemas);
+      return prev;
+    }, {});
+  }
+
+  if (schema.additionalProperties) {
+    schema.additionalProperties =
+      typeof schema.additionalProperties != 'boolean'
+        ? extractReferenceSchemas(schema.additionalProperties, referenceSchemas)
+        : schema.additionalProperties;
+  }
+
+  if (schema.title) {
+    const nullable = schema.nullable;
+    schema.nullable = undefined;
+    if (schema.title in referenceSchemas) {
+      if (
+        JSON.stringify(referenceSchemas[schema.title]) !==
+        JSON.stringify(schema)
+      ) {
+        throw new Error(
+          `Schema title '${schema.title}' already exists with a different schema`,
+        );
+      }
+    } else {
+      referenceSchemas[schema.title] = schema;
+    }
+
+    if (nullable) {
+      schema = {
+        nullable: true,
+        allOf: [
+          {
+            $ref: `#/components/schemas/${schema.title}`,
+          },
+        ],
+      };
+    } else {
+      schema = {
+        $ref: `#/components/schemas/${schema.title}`,
+      };
+    }
+  }
+  return schema;
+};
 /**
  *
  * @param options.jsonQuery - Enable JSON query parameters, [see](/docs/open-api#json-query-params)
@@ -216,6 +296,8 @@ export const generateOpenApi = (
 
   const operationIds = new Map<string, string[]>();
 
+  const referenceSchemas: { [id: string]: SchemaObject } = {};
+
   const pathObject = paths.reduce((acc, path) => {
     if (options.setOperationId === true) {
       const existingOp = operationIds.get(path.id);
@@ -235,19 +317,30 @@ export const generateOpenApi = (
       !!options.jsonQuery,
     );
 
-    const bodySchema =
+    let bodySchema =
       path.route?.method !== 'GET' && 'body' in path.route
         ? getOpenApiSchemaFromZod(path.route.body)
         : null;
 
+    if (bodySchema?.title) {
+      bodySchema = extractReferenceSchemas(bodySchema, referenceSchemas);
+    }
+
     const responses = Object.entries(path.route.responses).reduce(
       (acc, [statusCode, response]) => {
-        const responseSchema = getOpenApiSchemaFromZod(response, true);
+        let responseSchema = getOpenApiSchemaFromZod(response, true);
         const description =
           isZodType(response) && response.description
             ? response.description
             : statusCode;
 
+        if (responseSchema) {
+          responseSchema = extractReferenceSchemas(
+            responseSchema,
+            referenceSchemas,
+          );
+        }
+
         return {
           ...acc,
           [statusCode]: {
@@ -311,6 +404,15 @@ export const generateOpenApi = (
     return acc;
   }, {} as PathsObject);
 
+  if (Object.keys(referenceSchemas).length) {
+    apiDoc['components'] = {
+      schemas: {
+        ...referenceSchemas,
+      },
+      ...apiDoc['components'],
+    };
+  }
+
   return {
     openapi: '3.0.2',
     paths: pathObject,