@sapporta/rest-open-api 3.52.1

package/src/lib/parsers/utils.spec.ts

@@ -0,0 +1,117 @@
+import { SchemaObject } from 'openapi3-ts';
+import { schemaObjectToParameters } from './utils';
+import { z } from 'zod';
+import { zodV4SchemaTransformer } from './test-helpers';
+
+const generateSchema = (schema: z.ZodTypeAny): SchemaObject => {
+  return zodV4SchemaTransformer({
+    schema,
+    appRoute: {
+      method: 'GET',
+      path: '/',
+      responses: {},
+    },
+    id: 'test',
+    concatenatedPath: 'test',
+    type: 'query',
+  })!;
+};
+
+describe('utils', () => {
+  describe('schemaObjectToParameters', () => {
+    const schema: SchemaObject = {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    };
+
+    const parameters = schemaObjectToParameters(schema, 'query');
+
+    it('should return an array of parameters', () => {
+      expect(parameters).toEqual([
+        {
+          name: 'name',
+          in: 'query',
+          required: true,
+          schema: { type: 'string' },
+        },
+      ]);
+    });
+
+    it('should return an empty array if the schema is not an object', () => {
+      const schema: SchemaObject = { type: 'string' };
+      const parameters = schemaObjectToParameters(schema, 'query');
+      expect(parameters).toEqual([]);
+    });
+
+    it('should return optional parameters if the schema is not required', async () => {
+      const schema = generateSchema(
+        z.object({
+          name: z.string().optional(),
+        }),
+      );
+
+      const parameters = schemaObjectToParameters(schema, 'query');
+      expect(parameters).toEqual([
+        {
+          name: 'name',
+          in: 'query',
+          schema: { type: 'string' },
+        },
+      ]);
+    });
+
+    it("should inlude `style: 'deepObject'` if the schema is a deep object", () => {
+      const schema = generateSchema(
+        z.object({
+          parent: z.object({
+            child: z.string(),
+          }),
+        }),
+      );
+
+      const parameters = schemaObjectToParameters(schema, 'query');
+
+      expect(parameters).toEqual([
+        {
+          name: 'parent',
+          in: 'query',
+          required: true,
+          schema: {
+            additionalProperties: false,
+            properties: {
+              child: { type: 'string' },
+            },
+            required: ['child'],
+            type: 'object',
+          },
+          style: 'deepObject',
+        },
+      ]);
+    });
+
+    it('should work for jsonQuery', () => {
+      const schema = generateSchema(
+        z.object({
+          name: z.string(),
+        }),
+      );
+
+      const parameters = schemaObjectToParameters(schema, 'query', true);
+      expect(parameters).toEqual([
+        {
+          name: 'name',
+          in: 'query',
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      ]);
+    });
+  });
+});

package/src/lib/parsers/utils.ts

@@ -0,0 +1,82 @@
+import { ExamplesObject, ParameterObject, SchemaObject } from 'openapi3-ts';
+
+export const schemaToParameter = (
+  schema: SchemaObject,
+  where: 'query' | 'header' | 'path',
+  required: boolean,
+  key: string,
+  jsonQuery: boolean,
+): ParameterObject => {
+  let description: string | undefined = undefined;
+
+  if ('description' in schema) {
+    description = schema['description'];
+    delete schema['description'];
+  }
+
+  let examples: ExamplesObject | undefined = undefined;
+  if ('mediaExamples' in schema) {
+    examples = schema['mediaExamples'];
+    delete schema['mediaExamples'];
+  }
+
+  const isDeepObject = 'properties' in schema;
+
+  if (jsonQuery) {
+    return {
+      name: key,
+      in: where,
+      ...(description && { description }),
+      ...(required && { required }),
+      content: {
+        'application/json': {
+          schema,
+          ...(examples && { examples }),
+        },
+      },
+    };
+  } else {
+    return {
+      name: key,
+      in: where,
+      ...(examples && { examples }),
+      ...(description && { description }),
+      ...(required && { required }),
+      ...(isDeepObject && !jsonQuery && { style: 'deepObject' }),
+      schema,
+    };
+  }
+};
+
+/**
+ * Convert a @type {SchemaObject} to an array of @type {ParameterObject}
+ *
+ * @param schema - Zod 4 JSON schema output
+ * @param where - The location of the parameters
+ * @param jsonQuery - Whether the schema is a JSON query
+ * @returns The parameters for the schema
+ */
+export const schemaObjectToParameters = (
+  schema: SchemaObject,
+  where: 'query' | 'header' | 'path',
+  jsonQuery = false,
+): ParameterObject[] => {
+  const parameters: ParameterObject[] = [];
+
+  if (schema.type === 'object') {
+    const requiredSet = new Set(schema.required ?? []);
+    const properties = schema.properties;
+
+    if (!properties) {
+      return [];
+    }
+
+    for (const [key, value] of Object.entries(properties)) {
+      parameters.push(
+        schemaToParameter(value, where, requiredSet.has(key), key, jsonQuery),
+      );
+    }
+  }
+
+  return parameters;
+};

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

@@ -0,0 +1,245 @@
+import {
+  type AppRoute,
+  type AppRouter,
+  isAppRouteOtherResponse,
+} from '@sapporta/rest-core';
+import type {
+  ExamplesObject,
+  InfoObject,
+  OpenAPIObject,
+  OperationObject,
+  PathsObject,
+  SchemaObject,
+} from 'openapi3-ts';
+import {
+  PathSchemaResults,
+  RouterPath,
+  SchemaTransformerAsync,
+  SchemaTransformerSync,
+} from './types';
+import { performContractTraversal } from './contract-traversal';
+import {
+  convertSchemaObjectToMediaTypeObject,
+  extractReferenceSchemas,
+} from './utils';
+
+declare module 'openapi3-ts' {
+  interface SchemaObject {
+    mediaExamples?: ExamplesObject;
+  }
+}
+
+/**
+ * Generate OpenAPI specification from ts-rest router
+ *
+ * @param router - The ts-rest router to generate OpenAPI from
+ * @param apiDoc - Base OpenAPI document configuration
+ * @param options - Generation options
+ * @param options.setOperationId - Whether to set operation IDs (true, false, or 'concatenated-path')
+ * @param options.jsonQuery - Enable JSON query parameters, [see](/docs/open-api#json-query-params)
+ * @param options.operationMapper - Function to customize OpenAPI operations. Receives the operation object, app route, and operation ID
+ * @returns OpenAPI specification object
+ */
+export function generateOpenApi(
+  router: AppRouter,
+  apiDoc: Omit<OpenAPIObject, 'paths' | 'openapi'> & { info: InfoObject },
+  options: {
+    setOperationId?: boolean | 'concatenated-path';
+    jsonQuery?: boolean;
+    operationMapper?: (
+      operation: OperationObject,
+      appRoute: AppRoute,
+      id: string,
+    ) => OperationObject;
+    schemaTransformer: SchemaTransformerSync;
+  },
+): OpenAPIObject {
+  const paths = performContractTraversal.sync({
+    contract: router,
+    transformSchema: options?.schemaTransformer,
+    jsonQuery: !!options?.jsonQuery,
+  });
+
+  return traversedPathsToOpenApi(paths, apiDoc, {
+    setOperationId: options?.setOperationId,
+    jsonQuery: options?.jsonQuery,
+    operationMapper: options?.operationMapper,
+  });
+}
+
+/**
+ * Generate OpenAPI specification from ts-rest router with custom schema transformer
+ *
+ * @param router - The ts-rest router to generate OpenAPI from
+ * @param apiDoc - Base OpenAPI document configuration
+ * @param options - Generation options
+ * @param options.setOperationId - Whether to set operation IDs (true, false, or 'concatenated-path')
+ * @param options.jsonQuery - Enable JSON query parameters, [see](/docs/open-api#json-query-params)
+ * @param options.operationMapper - Function to customize OpenAPI operations. Receives the operation object, app route, and operation ID
+ * @param options.schemaTransformer - Custom schema transformer function.
+ */
+export async function generateOpenApiAsync(
+  router: AppRouter,
+  apiDoc: Omit<OpenAPIObject, 'paths' | 'openapi'> & { info: InfoObject },
+  options: {
+    setOperationId?: boolean | 'concatenated-path';
+    jsonQuery?: boolean;
+    operationMapper?: (
+      operation: OperationObject,
+      appRoute: AppRoute,
+      id: string,
+    ) => OperationObject;
+    schemaTransformer: SchemaTransformerAsync;
+  },
+): Promise<OpenAPIObject> {
+  const paths = await performContractTraversal.async({
+    contract: router,
+    transformSchema: options.schemaTransformer,
+    jsonQuery: !!options.jsonQuery,
+  });
+
+  return traversedPathsToOpenApi(paths, apiDoc, {
+    setOperationId: options.setOperationId,
+    jsonQuery: options.jsonQuery,
+    operationMapper: options.operationMapper,
+  });
+}
+
+/**
+ * Inner function to be reused by both sync and async functions
+ */
+const traversedPathsToOpenApi = (
+  paths: Array<RouterPath & { schemaResults: PathSchemaResults }>,
+  apiDoc: Omit<OpenAPIObject, 'paths' | 'openapi'> & { info: InfoObject },
+  options: {
+    setOperationId?: boolean | 'concatenated-path';
+    jsonQuery?: boolean;
+    operationMapper?: (
+      operation: OperationObject,
+      appRoute: AppRoute,
+      id: string,
+    ) => OperationObject;
+  },
+) => {
+  const mapMethod = {
+    GET: 'get',
+    POST: 'post',
+    PUT: 'put',
+    DELETE: 'delete',
+    PATCH: 'patch',
+  };
+
+  const operationIds = new Map<string, string[]>();
+
+  const referenceSchemas: { [id: string]: SchemaObject } = {};
+
+  const pathObject: PathsObject = {};
+
+  for (const path of paths) {
+    if (options.setOperationId === true) {
+      const existingOp = operationIds.get(path.id);
+      if (existingOp) {
+        throw new Error(
+          `Route '${path.id}' already defined under ${existingOp.join('.')}`,
+        );
+      }
+      operationIds.set(path.id, path.paths);
+    }
+
+    const _bodySchema = path.schemaResults.body;
+    const bodySchema =
+      _bodySchema && typeof _bodySchema === 'object' && 'title' in _bodySchema
+        ? extractReferenceSchemas(
+            path.schemaResults.body as SchemaObject,
+            referenceSchemas,
+          )
+        : path.schemaResults.body;
+
+    const responses: Record<string, SchemaObject> = {};
+
+    for (const [statusCode, response] of Object.entries(path.route.responses)) {
+      const contentType = isAppRouteOtherResponse(response)
+        ? response.contentType
+        : 'application/json';
+
+      const responseSchemaObject = path.schemaResults.responses[statusCode];
+      const responseSchemaObjectWithReferences = responseSchemaObject
+        ? extractReferenceSchemas(responseSchemaObject, referenceSchemas)
+        : null;
+
+      responses[statusCode] = {
+        ...(responseSchemaObjectWithReferences
+          ? {
+              content: {
+                [contentType]: {
+                  ...convertSchemaObjectToMediaTypeObject(
+                    responseSchemaObjectWithReferences,
+                  ),
+                },
+              },
+            }
+          : {}),
+      };
+    }
+
+    const contentType =
+      path.route?.method !== 'GET' && 'contentType' in path.route
+        ? path.route?.contentType ?? 'application/json'
+        : 'application/json';
+
+    const pathOperation: OperationObject = {
+      description: path.route.description,
+      summary: path.route.summary,
+      deprecated: path.route.deprecated,
+      tags: path.paths,
+      parameters: [
+        ...path.schemaResults.path,
+        ...path.schemaResults.headers,
+        ...path.schemaResults.query,
+      ],
+      ...(options.setOperationId
+        ? {
+            operationId:
+              options.setOperationId === 'concatenated-path'
+                ? [...path.paths, path.id].join('.')
+                : path.id,
+          }
+        : {}),
+      ...(bodySchema
+        ? {
+            requestBody: {
+              description: 'Body',
+              content: {
+                [contentType]: {
+                  ...convertSchemaObjectToMediaTypeObject(bodySchema),
+                },
+              },
+            },
+          }
+        : {}),
+      responses,
+    };
+
+    pathObject[path.path] = {
+      ...pathObject[path.path],
+      [mapMethod[path.route.method]]: options.operationMapper
+        ? options.operationMapper(pathOperation, path.route, path.id)
+        : pathOperation,
+    };
+  }
+
+  if (Object.keys(referenceSchemas).length) {
+    apiDoc['components'] = {
+      schemas: {
+        ...referenceSchemas,
+      },
+      ...apiDoc['components'],
+    };
+  }
+
+  return {
+    openapi: '3.0.2',
+    paths: pathObject,
+    ...apiDoc,
+  };
+};

package/src/lib/types.ts

@@ -0,0 +1,109 @@
+import { AppRoute } from '@sapporta/rest-core';
+import { ParameterObject, ResponseObject, SchemaObject } from 'openapi3-ts';
+
+type SchemaTransformerArgs = {
+  /**
+   * The schema to transform.
+   */
+  schema: unknown;
+  /**
+   * The app route.
+   */
+  appRoute: AppRoute;
+  /**
+   * The key of the route in a contract e.g. `getPokemon` or `createPokemon`.
+   */
+  id: string;
+  /**
+   * The concatenated path of the route. e.g. `pokemon.getPokemon` or `pokemon.createPokemon`.
+   */
+  concatenatedPath: string;
+  /**
+   * Where the schema is used, can be used to conditionally transform the schema.
+   */
+  type: 'body' | 'response' | 'query' | 'header' | 'path';
+};
+
+/**
+ * Sync schema transformer.
+ *
+ * This will be invoked for all schemas, e.g. every query, pathParam, body, etc.
+ *
+ * You should guard against your schema type here, and return null if it's not the schema you want to transform.
+ */
+export type SchemaTransformerSync = (
+  args: SchemaTransformerArgs,
+) => SchemaObject | null;
+
+/**
+ * Async schema transformer.
+ *
+ * This will be invoked for all schemas, e.g. every query, pathParam, body, etc.
+ *
+ * You should guard against your schema type here, and return null if it's not the schema you want to transform.
+ */
+export type SchemaTransformerAsync = (
+  args: SchemaTransformerArgs,
+) => Promise<SchemaObject | null>;
+
+export type SchemaTransformer = SchemaTransformerSync | SchemaTransformerAsync;
+
+/**
+ * We need to have many functions that are the same, but some are sync and some are async.
+ *
+ * This helper lets us make this trivial and avoids having different types for each function.
+ *
+ * @hidden
+ */
+export type AsyncAndSyncHelper<T, TFuncSyncArgs, TFuncAsyncArgs, TReturn> = {
+  sync: (args: T & TFuncSyncArgs) => TReturn;
+  async: (args: T & TFuncAsyncArgs) => Promise<TReturn>;
+};
+
+/**
+ * @hidden
+ */
+export type GetSyncFunction<THelper> = THelper extends AsyncAndSyncHelper<
+  any,
+  any,
+  any,
+  any
+>
+  ? THelper['sync']
+  : never;
+
+/**
+ * @hidden
+ */
+export type GetAsyncFunction<THelper> = THelper extends AsyncAndSyncHelper<
+  any,
+  any,
+  any,
+  any
+>
+  ? THelper['async']
+  : never;
+
+/**
+ * @hidden
+ */
+export type RouterPath = {
+  id: string;
+  path: string;
+  route: AppRoute;
+  paths: string[];
+};
+
+/**
+ * @hidden
+ */
+export type PathSchemaResults = {
+  path: ParameterObject[];
+  headers: ParameterObject[];
+  query: ParameterObject[];
+  body: SchemaObject | null;
+  /**
+   * Status code to response.
+   */
+  responses: Record<string, SchemaObject>;
+};

package/src/lib/utils.ts

@@ -0,0 +1,92 @@
+import { SchemaObject, MediaTypeObject, ReferenceObject } from 'openapi3-ts';
+
+export const convertSchemaObjectToMediaTypeObject = (
+  input: SchemaObject,
+): MediaTypeObject => {
+  const { mediaExamples: examples, ...schema } = input;
+
+  return {
+    schema,
+    ...(examples && { examples }),
+  };
+};
+
+export 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;
+};

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../dist/out-tsc",
+    "declaration": true,
+    "types": []
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["jest.config.ts", "**/*.spec.ts", "**/*.test.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node"]
+  },
+  "include": ["jest.config.ts", "**/*.test.ts", "**/*.spec.ts", "**/*.d.ts"]
+}

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "extends": ["../../../typedoc.base.json"],
+  "entryPoints": ["src/index.ts"],
+  "tsconfig": "./tsconfig.lib.json"
+}