@sapporta/rest-open-api 3.52.1 → 3.52.2

package/src/lib/contract-traversal.d.ts

@@ -0,0 +1,14 @@
+import { AppRouter } from '@sapporta/rest-core';
+import { AsyncAndSyncHelper, PathSchemaResults, RouterPath, SchemaTransformerAsync, SchemaTransformerSync } from './types';
+type PerformContractTraversalHelper = AsyncAndSyncHelper<{
+    contract: AppRouter;
+    jsonQuery: boolean;
+}, {
+    transformSchema: SchemaTransformerSync;
+}, {
+    transformSchema: SchemaTransformerAsync;
+}, Array<RouterPath & {
+    schemaResults: PathSchemaResults;
+}>>;
+export declare const performContractTraversal: PerformContractTraversalHelper;
+export {};

package/src/lib/parsers/body.d.ts

@@ -0,0 +1,14 @@
+import { AppRoute } from '@sapporta/rest-core';
+import { AsyncAndSyncHelper, SchemaTransformerAsync, SchemaTransformerSync } from '../types';
+import { SchemaObject } from 'openapi3-ts';
+type GetBodySchemaHelper = AsyncAndSyncHelper<{
+    appRoute: AppRoute;
+    id: string;
+    concatenatedPath: string;
+}, {
+    transformSchema: SchemaTransformerSync;
+}, {
+    transformSchema: SchemaTransformerAsync;
+}, SchemaObject | null>;
+export declare const getBodySchema: GetBodySchemaHelper;
+export {};

package/src/lib/parsers/headers.d.ts

@@ -0,0 +1,14 @@
+import { AppRoute } from '@sapporta/rest-core';
+import { AsyncAndSyncHelper, SchemaTransformerAsync, SchemaTransformerSync } from '../types';
+import { ParameterObject } from 'openapi3-ts';
+type GetHeaderParameterHelper = AsyncAndSyncHelper<{
+    appRoute: AppRoute;
+    id: string;
+    concatenatedPath: string;
+}, {
+    transformSchema: SchemaTransformerSync;
+}, {
+    transformSchema: SchemaTransformerAsync;
+}, Array<ParameterObject>>;
+export declare const getHeaderParameterSchema: GetHeaderParameterHelper;
+export {};

package/src/lib/parsers/path-params.d.ts

@@ -0,0 +1,20 @@
+import { AppRoute } from '@sapporta/rest-core';
+import { AsyncAndSyncHelper, SchemaTransformerAsync, SchemaTransformerSync } from '../types';
+import { ParameterObject } from 'openapi3-ts';
+type GetPathParameterHelper = AsyncAndSyncHelper<{
+    appRoute: AppRoute;
+    id: string;
+    concatenatedPath: string;
+}, {
+    transformSchema: SchemaTransformerSync;
+}, {
+    transformSchema: SchemaTransformerAsync;
+}, Array<ParameterObject>>;
+/**
+ * We build up the params from both the path and the schema.
+ *
+ * This builds up the record of name -> parameter object.
+ */
+export declare const getParamsFromPathOnly: (path: string) => Map<string, ParameterObject>;
+export declare const getPathParameterSchema: GetPathParameterHelper;
+export {};

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

@@ -0,0 +1,15 @@
+import { AppRoute } from '@sapporta/rest-core';
+import { AsyncAndSyncHelper, SchemaTransformerAsync, SchemaTransformerSync } from '../types';
+import { ParameterObject } from 'openapi3-ts';
+type GetQueryParameterHelper = AsyncAndSyncHelper<{
+    appRoute: AppRoute;
+    id: string;
+    concatenatedPath: string;
+    jsonQuery?: boolean;
+}, {
+    transformSchema: SchemaTransformerSync;
+}, {
+    transformSchema: SchemaTransformerAsync;
+}, Array<ParameterObject>>;
+export declare const getQueryParameterSchema: GetQueryParameterHelper;
+export {};

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

@@ -0,0 +1,4 @@
+import { SchemaTransformerAsync, SchemaTransformerSync } from '../types';
+export declare const zodV4SchemaTransformer: SchemaTransformerSync;
+export declare const ZOD_SYNC: SchemaTransformerSync;
+export declare const ZOD_ASYNC: SchemaTransformerAsync;

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

@@ -0,0 +1,11 @@
+import { ParameterObject, SchemaObject } from 'openapi3-ts';
+export declare const schemaToParameter: (schema: SchemaObject, where: 'query' | 'header' | 'path', required: boolean, key: string, jsonQuery: boolean) => ParameterObject;
+/**
+ * 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 declare const schemaObjectToParameters: (schema: SchemaObject, where: 'query' | 'header' | 'path', jsonQuery?: boolean) => ParameterObject[];

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

@@ -0,0 +1,46 @@
+import { type AppRoute, type AppRouter } from '@sapporta/rest-core';
+import type { ExamplesObject, InfoObject, OpenAPIObject, OperationObject } from 'openapi3-ts';
+import { SchemaTransformerAsync, SchemaTransformerSync } from './types';
+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 declare 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;
+/**
+ * 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 declare 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>;

package/src/lib/types.d.ts

@@ -0,0 +1,83 @@
+import { AppRoute } from '@sapporta/rest-core';
+import { ParameterObject, 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>;
+};
+export {};

package/src/lib/utils.d.ts

@@ -0,0 +1,5 @@
+import { SchemaObject, MediaTypeObject } from 'openapi3-ts';
+export declare const convertSchemaObjectToMediaTypeObject: (input: SchemaObject) => MediaTypeObject;
+export declare const extractReferenceSchemas: (schema: SchemaObject, referenceSchemas: {
+    [id: string]: SchemaObject;
+}) => SchemaObject;

package/.babelrc

@@ -1,10 +0,0 @@
-{
-  "presets": [
-    [
-      "@nrwl/js/babel",
-      {
-        "useBuiltIns": "usage"
-      }
-    ]
-  ]
-}

package/.eslintrc.json

@@ -1,21 +0,0 @@
-{
-  "extends": ["../../../.eslintrc.json"],
-  "ignorePatterns": ["!**/*"],
-  "overrides": [
-    {
-      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-      "rules": {
-        "@typescript-eslint/no-unused-vars": ["warn"],
-        "@typescript-eslint/no-explicit-any": ["warn"]
-      }
-    },
-    {
-      "files": ["*.ts", "*.tsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.js", "*.jsx"],
-      "rules": {}
-    }
-  ]
-}

package/jest.config.ts

@@ -1,16 +0,0 @@
-/* eslint-disable */
-export default {
-  displayName: 'sapporta-rest-open-api',
-  preset: '../../../jest.preset.js',
-  globals: {},
-  transform: {
-    '^.+\\.[tj]s$': [
-      'ts-jest',
-      {
-        tsconfig: '<rootDir>/tsconfig.spec.json',
-      },
-    ],
-  },
-  moduleFileExtensions: ['ts', 'js', 'html'],
-  testEnvironment: 'node',
-};

package/project.json

@@ -1,51 +0,0 @@
-{
-  "name": "sapporta-rest-open-api",
-  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "libs/ts-rest/open-api/src",
-  "projectType": "library",
-  "targets": {
-    "build": {
-      "executor": "@nx/rollup:rollup",
-      "outputs": ["{options.outputPath}"],
-      "options": {
-        "project": "libs/ts-rest/open-api/package.json",
-        "outputPath": "dist/libs/ts-rest/open-api",
-        "main": "libs/ts-rest/open-api/src/index.ts",
-        "tsConfig": "libs/ts-rest/open-api/tsconfig.lib.json",
-        "assets": [
-          {
-            "glob": "CHANGELOG.md",
-            "input": "libs/ts-rest/open-api",
-            "output": "."
-          },
-          {
-            "glob": "README.md",
-            "input": ".",
-            "output": "."
-          }
-        ],
-        "format": ["esm", "cjs"],
-        "compiler": "tsc",
-        "rollupConfig": "tools/scripts/rollup.config.js",
-        "generateExportsField": true,
-        "updateBuildableProjectDepsInPackageJson": true
-      }
-    },
-    "lint": {
-      "executor": "@nx/eslint:lint",
-      "outputs": ["{options.outputFile}"],
-      "options": {
-        "lintFilePatterns": ["libs/ts-rest/open-api/**/*.ts"],
-        "ignorePath": ".gitignore"
-      }
-    },
-    "test": {
-      "executor": "@nx/jest:jest",
-      "outputs": ["{workspaceRoot}/coverage/libs/ts-rest/open-api"],
-      "options": {
-        "jestConfig": "libs/ts-rest/open-api/jest.config.ts"
-      }
-    }
-  },
-  "tags": []
-}

package/src/index.ts

@@ -1,6 +0,0 @@
-export * from './lib/ts-rest-open-api';
-export {
-  SchemaTransformer,
-  SchemaTransformerAsync,
-  SchemaTransformerSync,
-} from './lib/types';

package/src/lib/contract-traversal.ts

@@ -1,217 +0,0 @@
-import { AppRouter, isAppRoute, isAppRouteOtherResponse } from '@sapporta/rest-core';
-import {
-  AsyncAndSyncHelper,
-  GetAsyncFunction,
-  GetSyncFunction,
-  PathSchemaResults,
-  RouterPath,
-  SchemaTransformerAsync,
-  SchemaTransformerSync,
-} from './types';
-import { getPathParameterSchema } from './parsers/path-params';
-import { getHeaderParameterSchema } from './parsers/headers';
-import { getQueryParameterSchema } from './parsers/query-params';
-import { getBodySchema } from './parsers/body';
-import { SchemaObject } from 'openapi3-ts';
-
-type PerformContractTraversalHelper = AsyncAndSyncHelper<
-  {
-    contract: AppRouter;
-    jsonQuery: boolean;
-  },
-  {
-    transformSchema: SchemaTransformerSync;
-  },
-  {
-    transformSchema: SchemaTransformerAsync;
-  },
-  Array<RouterPath & { schemaResults: PathSchemaResults }>
->;
-
-/**
- * Recursively step through the router and get all the individual routes with their paths etc.
- */
-const getPathsFromRouter = (
-  router: AppRouter,
-  pathHistory?: string[],
-): RouterPath[] => {
-  const paths: RouterPath[] = [];
-
-  Object.keys(router).forEach((key) => {
-    const value = router[key];
-
-    if (isAppRoute(value)) {
-      const pathWithPathParams = value.path.replace(/:(\w+)/g, '{$1}');
-
-      paths.push({
-        id: key,
-        path: pathWithPathParams,
-        route: value,
-        paths: pathHistory ?? [],
-      });
-    } else {
-      paths.push(...getPathsFromRouter(value, [...(pathHistory ?? []), key]));
-    }
-  });
-
-  return paths;
-};
-
-const syncFunc: GetSyncFunction<PerformContractTraversalHelper> = ({
-  contract,
-  transformSchema,
-  jsonQuery,
-}) => {
-  const paths = getPathsFromRouter(contract);
-
-  const results: Array<RouterPath & { schemaResults: PathSchemaResults }> = [];
-
-  for (const path of paths) {
-    const concatenatedPath = [...path.paths, path.id].join('.');
-
-    const pathParams = getPathParameterSchema.sync({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-    });
-
-    const headerParams = getHeaderParameterSchema.sync({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-    });
-
-    const querySchema = getQueryParameterSchema.sync({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-      jsonQuery: !!jsonQuery,
-    });
-
-    const bodySchema = getBodySchema.sync({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-    });
-
-    const responses: Record<string, SchemaObject> = {};
-    for (const [statusCode, _response] of Object.entries(
-      path.route.responses,
-    )) {
-      const schemaValidator = isAppRouteOtherResponse(_response)
-        ? _response.body
-        : _response;
-
-      const responseSchema = transformSchema({
-        schema: schemaValidator,
-        appRoute: path.route,
-        id: path.id,
-        concatenatedPath,
-        type: 'response',
-      });
-
-      if (responseSchema) {
-        responses[statusCode] = responseSchema;
-      }
-    }
-
-    results.push({
-      ...path,
-      schemaResults: {
-        path: pathParams,
-        headers: headerParams,
-        query: querySchema,
-        body: bodySchema,
-        responses,
-      },
-    });
-  }
-
-  return results;
-};
-
-const asyncFunc: GetAsyncFunction<PerformContractTraversalHelper> = async ({
-  contract,
-  transformSchema,
-  jsonQuery,
-}) => {
-  const paths = getPathsFromRouter(contract);
-
-  const results: Array<RouterPath & { schemaResults: PathSchemaResults }> = [];
-
-  for (const path of paths) {
-    const concatenatedPath = [...path.paths, path.id].join('.');
-
-    const pathParams = await getPathParameterSchema.async({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-    });
-
-    const headerParams = await getHeaderParameterSchema.async({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-    });
-
-    const querySchema = await getQueryParameterSchema.async({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-      jsonQuery: !!jsonQuery,
-    });
-
-    const bodySchema = await getBodySchema.async({
-      transformSchema,
-      appRoute: path.route,
-      id: path.id,
-      concatenatedPath,
-    });
-
-    const responses: Record<string, SchemaObject> = {};
-    for (const [statusCode, _response] of Object.entries(
-      path.route.responses,
-    )) {
-      const schemaValidator = isAppRouteOtherResponse(_response)
-        ? _response.body
-        : _response;
-
-      const responseSchema = await transformSchema({
-        schema: schemaValidator,
-        appRoute: path.route,
-        id: path.id,
-        concatenatedPath,
-        type: 'response',
-      });
-
-      if (responseSchema) {
-        responses[statusCode] = responseSchema;
-      }
-    }
-
-    results.push({
-      ...path,
-      schemaResults: {
-        path: pathParams,
-        headers: headerParams,
-        query: querySchema,
-        body: bodySchema,
-        responses,
-      },
-    });
-  }
-
-  return results;
-};
-
-export const performContractTraversal: PerformContractTraversalHelper = {
-  sync: syncFunc,
-  async: asyncFunc,
-};

package/src/lib/parsers/body.ts

@@ -1,71 +0,0 @@
-import { AppRoute } from '@sapporta/rest-core';
-import {
-  AsyncAndSyncHelper,
-  GetAsyncFunction,
-  GetSyncFunction,
-  SchemaTransformerAsync,
-  SchemaTransformerSync,
-} from '../types';
-import { SchemaObject } from 'openapi3-ts';
-
-type GetBodySchemaHelper = AsyncAndSyncHelper<
-  {
-    appRoute: AppRoute;
-    id: string;
-    concatenatedPath: string;
-  },
-  {
-    transformSchema: SchemaTransformerSync;
-  },
-  {
-    transformSchema: SchemaTransformerAsync;
-  },
-  SchemaObject | null
->;
-
-const syncFunc: GetSyncFunction<GetBodySchemaHelper> = ({
-  transformSchema,
-  appRoute,
-  id,
-  concatenatedPath,
-}) => {
-  const schema = 'body' in appRoute ? appRoute.body : undefined;
-
-  const transformedSchema = transformSchema({
-    schema,
-    appRoute,
-    id,
-    concatenatedPath,
-    type: 'body',
-  });
-
-  if (!transformedSchema) {
-    return null;
-  }
-
-  return transformedSchema;
-};
-
-const asyncFunc: GetAsyncFunction<GetBodySchemaHelper> = async ({
-  transformSchema,
-  appRoute,
-  id,
-  concatenatedPath,
-}) => {
-  const schema = 'body' in appRoute ? appRoute.body : undefined;
-
-  const transformedSchema = await transformSchema({
-    schema,
-    appRoute,
-    id,
-    concatenatedPath,
-    type: 'body',
-  });
-
-  return transformedSchema;
-};
-
-export const getBodySchema: GetBodySchemaHelper = {
-  sync: syncFunc,
-  async: asyncFunc,
-};