@sapporta/rest-open-api 3.52.1 → 3.52.2

package/src/lib/parsers/query-params.ts

@@ -1,89 +0,0 @@
-import { AppRoute, isStandardSchema } from '@sapporta/rest-core';
-import {
-  AsyncAndSyncHelper,
-  GetAsyncFunction,
-  GetSyncFunction,
-  SchemaTransformerAsync,
-  SchemaTransformerSync,
-} from '../types';
-import { ParameterObject } from 'openapi3-ts';
-import { schemaObjectToParameters } from './utils';
-
-type GetQueryParameterHelper = AsyncAndSyncHelper<
-  {
-    appRoute: AppRoute;
-    id: string;
-    concatenatedPath: string;
-    jsonQuery?: boolean;
-  },
-  {
-    transformSchema: SchemaTransformerSync;
-  },
-  {
-    transformSchema: SchemaTransformerAsync;
-  },
-  Array<ParameterObject>
->;
-
-const syncFunc: GetSyncFunction<GetQueryParameterHelper> = ({
-  transformSchema,
-  appRoute,
-  id,
-  concatenatedPath,
-  jsonQuery = false,
-}) => {
-  const schema = appRoute.query;
-  const isSchema = isStandardSchema(schema);
-
-  if (!isSchema) {
-    return [];
-  }
-
-  const transformedSchema = transformSchema({
-    schema,
-    appRoute,
-    id,
-    concatenatedPath,
-    type: 'query',
-  });
-
-  if (!transformedSchema) {
-    return [];
-  }
-
-  return schemaObjectToParameters(transformedSchema, 'query', jsonQuery);
-};
-
-const asyncFunc: GetAsyncFunction<GetQueryParameterHelper> = async ({
-  transformSchema,
-  appRoute,
-  id,
-  concatenatedPath,
-  jsonQuery = false,
-}) => {
-  const schema = appRoute.query;
-  const isSchema = isStandardSchema(schema);
-
-  if (!isSchema) {
-    return [];
-  }
-
-  const transformedSchema = await transformSchema({
-    schema,
-    appRoute,
-    id,
-    concatenatedPath,
-    type: 'query',
-  });
-
-  if (!transformedSchema) {
-    return [];
-  }
-
-  return schemaObjectToParameters(transformedSchema, 'query', jsonQuery);
-};
-
-export const getQueryParameterSchema: GetQueryParameterHelper = {
-  sync: syncFunc,
-  async: asyncFunc,
-};

package/src/lib/parsers/test-helpers.ts

@@ -1,26 +0,0 @@
-import { SchemaObject } from 'openapi3-ts';
-import { z } from 'zod';
-import { SchemaTransformerAsync, SchemaTransformerSync } from '../types';
-
-const stripJsonSchemaMetadata = (schema: unknown): SchemaObject => {
-  if (!schema || typeof schema !== 'object') {
-    return schema as SchemaObject;
-  }
-
-  const { $schema, ...rest } = schema as Record<string, unknown>;
-  return rest as SchemaObject;
-};
-
-export const zodV4SchemaTransformer: SchemaTransformerSync = ({ schema }) => {
-  if (!schema || typeof schema !== 'object' || !('_zod' in schema)) {
-    return null;
-  }
-
-  return stripJsonSchemaMetadata(z.toJSONSchema(schema as z.ZodTypeAny));
-};
-
-export const ZOD_SYNC = zodV4SchemaTransformer;
-
-export const ZOD_ASYNC: SchemaTransformerAsync = async (args) => {
-  return zodV4SchemaTransformer(args);
-};

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

@@ -1,117 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,245 +0,0 @@
-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

@@ -1,109 +0,0 @@
-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>;
-};