@orpc/openapi 0.0.0-next.85df466 → 0.0.0-next.85e5dff

package/dist/index.mjs

@@ -1,18 +1,13 @@
-import { isProcedure, eachAllContractProcedure } from '@orpc/server';
-import { OpenApiBuilder } from 'openapi3-ts/oas31';
-export { OpenApiBuilder } from 'openapi3-ts/oas31';
-import { findDeepMatches, isObject, get, omit, group } from '@orpc/shared';
-import { fallbackORPCErrorStatus } from '@orpc/client';
+import { isProcedure, resolveContractProcedures } from '@orpc/server';
+import { fallbackORPCErrorStatus, fallbackORPCErrorMessage } from '@orpc/client';
+import { toHttpPath } from '@orpc/client/standard';
 import { fallbackContractConfig, getEventIteratorSchemaDetails } from '@orpc/contract';
-import { OpenAPIJsonSerializer } from '@orpc/openapi-client/standard';
-import * as draft202012 from 'json-schema-typed/draft-2020-12';
-export { draft202012 as JSONSchema };
+import { standardizeHTTPPath, StandardOpenAPIJsonSerializer, getDynamicParams } from '@orpc/openapi-client/standard';
+import { isObject, findDeepMatches, clone } from '@orpc/shared';
 export { Format as JSONSchemaFormat } from 'json-schema-typed/draft-2020-12';
-import { t as toOpenAPI31RoutePattern } from './shared/openapi.BHG_gu5Z.mjs';
-export { s as standardizeHTTPPath } from './shared/openapi.BHG_gu5Z.mjs';
 
 const OPERATION_EXTENDER_SYMBOL = Symbol("ORPC_OPERATION_EXTENDER");
-function setOperationExtender(o, extend) {
+function customOpenAPIOperation(o, extend) {
   return new Proxy(o, {
     get(target, prop, receiver) {
       if (prop === OPERATION_EXTENDER_SYMBOL) {
@@ -22,248 +17,258 @@ function setOperationExtender(o, extend) {
     }
   });
 }
-function getOperationExtender(o) {
+function getCustomOpenAPIOperation(o) {
   return o[OPERATION_EXTENDER_SYMBOL];
 }
-function extendOperation(operation, procedure) {
-  const operationExtenders = [];
-  for (const errorItem of Object.values(procedure["~orpc"].errorMap)) {
-    const maybeExtender = getOperationExtender(errorItem);
+function applyCustomOpenAPIOperation(operation, contract) {
+  const operationCustoms = [];
+  for (const errorItem of Object.values(contract["~orpc"].errorMap)) {
+    const maybeExtender = errorItem ? getCustomOpenAPIOperation(errorItem) : void 0;
     if (maybeExtender) {
-      operationExtenders.push(maybeExtender);
+      operationCustoms.push(maybeExtender);
     }
   }
-  if (isProcedure(procedure)) {
-    for (const middleware of procedure["~orpc"].middlewares) {
-      const maybeExtender = getOperationExtender(middleware);
+  if (isProcedure(contract)) {
+    for (const middleware of contract["~orpc"].middlewares) {
+      const maybeExtender = getCustomOpenAPIOperation(middleware);
       if (maybeExtender) {
-        operationExtenders.push(maybeExtender);
+        operationCustoms.push(maybeExtender);
       }
     }
   }
   let currentOperation = operation;
-  for (const extender of operationExtenders) {
-    if (typeof extender === "function") {
-      currentOperation = extender(currentOperation, procedure);
+  for (const custom of operationCustoms) {
+    if (typeof custom === "function") {
+      currentOperation = custom(currentOperation, contract);
     } else {
       currentOperation = {
         ...currentOperation,
-        ...extender
+        ...custom
       };
     }
   }
   return currentOperation;
 }
 
-class OpenAPIContentBuilder {
-  constructor(schemaUtils) {
-    this.schemaUtils = schemaUtils;
-  }
-  build(jsonSchema, options) {
-    const isFileSchema = this.schemaUtils.isFileSchema.bind(this.schemaUtils);
-    const [matches, schema] = this.schemaUtils.filterSchemaBranches(jsonSchema, isFileSchema);
-    const files = matches;
-    const content = {};
-    for (const file of files) {
-      content[file.contentMediaType] = {
-        schema: file
-      };
-    }
-    const isStillHasFileSchema = findDeepMatches(isFileSchema, schema).values.length > 0;
-    if (schema !== void 0) {
-      content[isStillHasFileSchema ? "multipart/form-data" : "application/json"] = {
-        schema,
-        ...options
-      };
-    }
-    return content;
-  }
-}
+const LOGIC_KEYWORDS = [
+  "$dynamicRef",
+  "$ref",
+  "additionalItems",
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "const",
+  "contains",
+  "contentEncoding",
+  "contentMediaType",
+  "contentSchema",
+  "dependencies",
+  "dependentRequired",
+  "dependentSchemas",
+  "else",
+  "enum",
+  "exclusiveMaximum",
+  "exclusiveMinimum",
+  "format",
+  "if",
+  "items",
+  "maxContains",
+  "maximum",
+  "maxItems",
+  "maxLength",
+  "maxProperties",
+  "minContains",
+  "minimum",
+  "minItems",
+  "minLength",
+  "minProperties",
+  "multipleOf",
+  "not",
+  "oneOf",
+  "pattern",
+  "patternProperties",
+  "prefixItems",
+  "properties",
+  "propertyNames",
+  "required",
+  "then",
+  "type",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+  "uniqueItems"
+];
 
-class OpenAPIError extends Error {
+function isFileSchema(schema) {
+  return isObject(schema) && schema.type === "string" && typeof schema.contentMediaType === "string";
 }
-
-class OpenAPIInputStructureParser {
-  constructor(schemaConverter, schemaUtils, pathParser) {
-    this.schemaConverter = schemaConverter;
-    this.schemaUtils = schemaUtils;
-    this.pathParser = pathParser;
+function isObjectSchema(schema) {
+  return isObject(schema) && schema.type === "object";
+}
+function isAnySchema(schema) {
+  if (schema === true) {
+    return true;
   }
-  parse(contract, structure) {
-    const inputSchema = this.schemaConverter.convert(contract["~orpc"].inputSchema, { strategy: "input" });
-    const method = fallbackContractConfig("defaultMethod", contract["~orpc"].route?.method);
-    const httpPath = contract["~orpc"].route?.path;
-    if (this.schemaUtils.isAnySchema(inputSchema)) {
-      return {
-        paramsSchema: void 0,
-        querySchema: void 0,
-        headersSchema: void 0,
-        bodySchema: void 0
-      };
-    }
-    if (structure === "detailed") {
-      return this.parseDetailedSchema(inputSchema);
-    } else {
-      return this.parseCompactSchema(inputSchema, method, httpPath);
-    }
+  if (Object.keys(schema).every((k) => !LOGIC_KEYWORDS.includes(k))) {
+    return true;
   }
-  parseDetailedSchema(inputSchema) {
-    if (!this.schemaUtils.isObjectSchema(inputSchema)) {
-      throw new OpenAPIError(`When input structure is 'detailed', input schema must be an object.`);
-    }
-    if (inputSchema.properties && Object.keys(inputSchema.properties).some((key) => !["params", "query", "headers", "body"].includes(key))) {
-      throw new OpenAPIError(`When input structure is 'detailed', input schema must be only can contain 'params', 'query', 'headers' and 'body' properties.`);
-    }
-    let paramsSchema = inputSchema.properties?.params;
-    let querySchema = inputSchema.properties?.query;
-    let headersSchema = inputSchema.properties?.headers;
-    const bodySchema = inputSchema.properties?.body;
-    if (paramsSchema !== void 0 && this.schemaUtils.isAnySchema(paramsSchema)) {
-      paramsSchema = void 0;
-    }
-    if (paramsSchema !== void 0 && !this.schemaUtils.isObjectSchema(paramsSchema)) {
-      throw new OpenAPIError(`When input structure is 'detailed', params schema in input schema must be an object.`);
-    }
-    if (querySchema !== void 0 && this.schemaUtils.isAnySchema(querySchema)) {
-      querySchema = void 0;
-    }
-    if (querySchema !== void 0 && !this.schemaUtils.isObjectSchema(querySchema)) {
-      throw new OpenAPIError(`When input structure is 'detailed', query schema in input schema must be an object.`);
-    }
-    if (headersSchema !== void 0 && this.schemaUtils.isAnySchema(headersSchema)) {
-      headersSchema = void 0;
+  return false;
+}
+function separateObjectSchema(schema, separatedProperties) {
+  if (Object.keys(schema).some((k) => k !== "type" && k !== "properties" && k !== "required" && LOGIC_KEYWORDS.includes(k))) {
+    return [{ type: "object" }, schema];
+  }
+  const matched = { ...schema };
+  const rest = { ...schema };
+  matched.properties = schema.properties && Object.entries(schema.properties).filter(([key]) => separatedProperties.includes(key)).reduce((acc, [key, value]) => {
+    acc[key] = value;
+    return acc;
+  }, {});
+  matched.required = schema.required?.filter((key) => separatedProperties.includes(key));
+  matched.examples = schema.examples?.map((example) => {
+    if (!isObject(example)) {
+      return example;
     }
-    if (headersSchema !== void 0 && !this.schemaUtils.isObjectSchema(headersSchema)) {
-      throw new OpenAPIError(`When input structure is 'detailed', headers schema in input schema must be an object.`);
+    return Object.entries(example).reduce((acc, [key, value]) => {
+      if (separatedProperties.includes(key)) {
+        acc[key] = value;
+      }
+      return acc;
+    }, {});
+  });
+  rest.properties = schema.properties && Object.entries(schema.properties).filter(([key]) => !separatedProperties.includes(key)).reduce((acc, [key, value]) => {
+    acc[key] = value;
+    return acc;
+  }, {});
+  rest.required = schema.required?.filter((key) => !separatedProperties.includes(key));
+  rest.examples = schema.examples?.map((example) => {
+    if (!isObject(example)) {
+      return example;
     }
-    return { paramsSchema, querySchema, headersSchema, bodySchema };
+    return Object.entries(example).reduce((acc, [key, value]) => {
+      if (!separatedProperties.includes(key)) {
+        acc[key] = value;
+      }
+      return acc;
+    }, {});
+  });
+  return [matched, rest];
+}
+function filterSchemaBranches(schema, check, matches = []) {
+  if (check(schema)) {
+    matches.push(schema);
+    return [matches, void 0];
   }
-  parseCompactSchema(inputSchema, method, httpPath) {
-    const dynamic = httpPath ? this.pathParser.parseDynamicParams(httpPath) : [];
-    if (dynamic.length === 0) {
-      if (method === "GET") {
-        let querySchema = inputSchema;
-        if (querySchema !== void 0 && this.schemaUtils.isAnySchema(querySchema)) {
-          querySchema = void 0;
+  if (isObject(schema)) {
+    for (const keyword of ["anyOf", "oneOf"]) {
+      if (schema[keyword] && Object.keys(schema).every(
+        (k) => k === keyword || !LOGIC_KEYWORDS.includes(k)
+      )) {
+        const rest = schema[keyword].map((s) => filterSchemaBranches(s, check, matches)[1]).filter((v) => !!v);
+        if (rest.length === 1 && typeof rest[0] === "object") {
+          return [matches, { ...schema, [keyword]: void 0, ...rest[0] }];
         }
-        if (querySchema !== void 0 && !this.schemaUtils.isObjectSchema(querySchema)) {
-          throw new OpenAPIError(`When input structure is 'compact' and method is 'GET', input schema must be an object.`);
-        }
-        return {
-          paramsSchema: void 0,
-          querySchema,
-          headersSchema: void 0,
-          bodySchema: void 0
-        };
+        return [matches, { ...schema, [keyword]: rest }];
       }
-      return {
-        paramsSchema: void 0,
-        querySchema: void 0,
-        headersSchema: void 0,
-        bodySchema: inputSchema
-      };
     }
-    if (!this.schemaUtils.isObjectSchema(inputSchema)) {
-      throw new OpenAPIError(`When input structure is 'compact' and path has dynamic parameters, input schema must be an object.`);
-    }
-    const [params, rest] = this.schemaUtils.separateObjectSchema(inputSchema, dynamic.map((v) => v.name));
-    return {
-      paramsSchema: params,
-      querySchema: method === "GET" ? rest : void 0,
-      headersSchema: void 0,
-      bodySchema: method !== "GET" ? rest : void 0
-    };
   }
+  return [matches, schema];
 }
 
-class OpenAPIOutputStructureParser {
-  constructor(schemaConverter, schemaUtils) {
-    this.schemaConverter = schemaConverter;
-    this.schemaUtils = schemaUtils;
+function toOpenAPIPath(path) {
+  return standardizeHTTPPath(path).replace(/\/\{\+([^}]+)\}/g, "/{$1}");
+}
+function toOpenAPIMethod(method) {
+  return method.toLocaleLowerCase();
+}
+function toOpenAPIContent(schema) {
+  const content = {};
+  const [matches, restSchema] = filterSchemaBranches(schema, isFileSchema);
+  for (const file of matches) {
+    content[file.contentMediaType] = {
+      schema: toOpenAPISchema(file)
+    };
   }
-  parse(contract, structure) {
-    const outputSchema = this.schemaConverter.convert(contract["~orpc"].outputSchema, { strategy: "output" });
-    if (this.schemaUtils.isAnySchema(outputSchema)) {
-      return {
-        headersSchema: void 0,
-        bodySchema: void 0
+  if (restSchema !== void 0) {
+    content["application/json"] = {
+      schema: toOpenAPISchema(restSchema)
+    };
+    const isStillHasFileSchema = findDeepMatches((v) => isObject(v) && isFileSchema(v), restSchema).values.length > 0;
+    if (isStillHasFileSchema) {
+      content["multipart/form-data"] = {
+        schema: toOpenAPISchema(restSchema)
       };
     }
-    if (structure === "detailed") {
-      return this.parseDetailedSchema(outputSchema);
-    } else {
-      return this.parseCompactSchema(outputSchema);
-    }
   }
-  parseDetailedSchema(outputSchema) {
-    if (!this.schemaUtils.isObjectSchema(outputSchema)) {
-      throw new OpenAPIError(`When output structure is 'detailed', output schema must be an object.`);
-    }
-    if (outputSchema.properties && Object.keys(outputSchema.properties).some((key) => !["headers", "body"].includes(key))) {
-      throw new OpenAPIError(`When output structure is 'detailed', output schema must be only can contain 'headers' and 'body' properties.`);
-    }
-    let headersSchema = outputSchema.properties?.headers;
-    const bodySchema = outputSchema.properties?.body;
-    if (headersSchema !== void 0 && this.schemaUtils.isAnySchema(headersSchema)) {
-      headersSchema = void 0;
-    }
-    if (headersSchema !== void 0 && !this.schemaUtils.isObjectSchema(headersSchema)) {
-      throw new OpenAPIError(`When output structure is 'detailed', headers schema in output schema must be an object.`);
+  return content;
+}
+function toOpenAPIEventIteratorContent([yieldsRequired, yieldsSchema], [returnsRequired, returnsSchema]) {
+  return {
+    "text/event-stream": {
+      schema: toOpenAPISchema({
+        oneOf: [
+          {
+            type: "object",
+            properties: {
+              event: { const: "message" },
+              data: yieldsSchema,
+              id: { type: "string" },
+              retry: { type: "number" }
+            },
+            required: yieldsRequired ? ["event", "data"] : ["event"]
+          },
+          {
+            type: "object",
+            properties: {
+              event: { const: "done" },
+              data: returnsSchema,
+              id: { type: "string" },
+              retry: { type: "number" }
+            },
+            required: returnsRequired ? ["event", "data"] : ["event"]
+          },
+          {
+            type: "object",
+            properties: {
+              event: { const: "error" },
+              data: {},
+              id: { type: "string" },
+              retry: { type: "number" }
+            },
+            required: ["event"]
+          }
+        ]
+      })
     }
-    return { headersSchema, bodySchema };
-  }
-  parseCompactSchema(outputSchema) {
-    return {
-      headersSchema: void 0,
-      bodySchema: outputSchema
-    };
+  };
+}
+function toOpenAPIParameters(schema, parameterIn) {
+  const parameters = [];
+  for (const key in schema.properties) {
+    const keySchema = schema.properties[key];
+    parameters.push({
+      name: key,
+      in: parameterIn,
+      required: schema.required?.includes(key),
+      style: parameterIn === "query" ? "deepObject" : void 0,
+      explode: parameterIn === "query" ? true : void 0,
+      schema: toOpenAPISchema(keySchema)
+    });
   }
+  return parameters;
 }
-
-class OpenAPIParametersBuilder {
-  build(paramIn, jsonSchema, options) {
-    const parameters = [];
-    for (const name in jsonSchema.properties) {
-      const schema = jsonSchema.properties[name];
-      const paramExamples = jsonSchema.examples?.filter((example) => {
-        return isObject(example) && name in example;
-      }).map((example) => {
-        return example[name];
-      });
-      const paramSchema = {
-        examples: paramExamples?.length ? paramExamples : void 0,
-        ...schema === true ? {} : schema === false ? { not: {} } : schema
-      };
-      const paramExample = get(options?.example, [name]);
-      parameters.push({
-        name,
-        in: paramIn,
-        required: typeof options?.required === "boolean" ? options.required : jsonSchema.required?.includes(name) ?? false,
-        schema: paramSchema,
-        example: paramExample,
-        style: options?.style
-      });
-    }
-    return parameters;
+function checkParamsSchema(schema, params) {
+  const properties = Object.keys(schema.properties ?? {});
+  const required = schema.required ?? [];
+  if (properties.length !== params.length || properties.some((v) => !params.includes(v))) {
+    return false;
   }
-  buildHeadersObject(jsonSchema, options) {
-    const parameters = this.build("header", jsonSchema, options);
-    const headersObject = {};
-    for (const param of parameters) {
-      headersObject[param.name] = omit(param, ["name", "in"]);
-    }
-    return headersObject;
+  if (required.length !== params.length || required.some((v) => !params.includes(v))) {
+    return false;
   }
+  return true;
 }
-
-class OpenAPIPathParser {
-  parseDynamicParams(path) {
-    const raws = path.match(/\{([^}]+)\}/g) ?? [];
-    return raws.map((raw) => {
-      const name = raw.slice(1, -1).split(":")[0];
-      return { name, raw };
-    });
-  }
+function toOpenAPISchema(schema) {
+  return schema === true ? {} : schema === false ? { not: {} } : schema;
 }
 
 class CompositeSchemaConverter {
@@ -271,327 +276,229 @@ class CompositeSchemaConverter {
   constructor(converters) {
     this.converters = converters;
   }
-  condition() {
-    return true;
-  }
   convert(schema, options) {
     for (const converter of this.converters) {
       if (converter.condition(schema, options)) {
         return converter.convert(schema, options);
       }
     }
-    return {};
+    return [false, {}];
   }
 }
 
-const NON_LOGIC_KEYWORDS = [
-  // Core Documentation Keywords
-  "$anchor",
-  "$comment",
-  "$defs",
-  "$id",
-  "title",
-  "description",
-  // Value Keywords
-  "default",
-  "deprecated",
-  "examples",
-  // Metadata Keywords
-  "$schema",
-  "definitions",
-  // Legacy, but still used
-  "readOnly",
-  "writeOnly",
-  // Display and UI Hints
-  "contentMediaType",
-  "contentEncoding",
-  "format",
-  // Custom Extensions
-  "$vocabulary",
-  "$dynamicAnchor",
-  "$dynamicRef"
-];
-
-class SchemaUtils {
-  isFileSchema(schema) {
-    return isObject(schema) && schema.type === "string" && typeof schema.contentMediaType === "string";
-  }
-  isObjectSchema(schema) {
-    return isObject(schema) && schema.type === "object";
-  }
-  isAnySchema(schema) {
-    return schema === true || Object.keys(schema).filter((key) => !NON_LOGIC_KEYWORDS.includes(key)).length === 0;
+class OpenAPIGeneratorError extends Error {
+}
+class OpenAPIGenerator {
+  serializer;
+  converter;
+  constructor(options = {}) {
+    this.serializer = new StandardOpenAPIJsonSerializer(options);
+    this.converter = new CompositeSchemaConverter(options.schemaConverters ?? []);
   }
-  isUndefinableSchema(schema) {
-    const [matches] = this.filterSchemaBranches(schema, (schema2) => {
-      if (typeof schema2 === "boolean") {
-        return schema2;
+  async generate(router, base) {
+    const doc = clone(base);
+    doc.openapi = "3.1.1";
+    const errors = [];
+    await resolveContractProcedures({ path: [], router }, ({ contract, path }) => {
+      const operationId = path.join(".");
+      try {
+        const def = contract["~orpc"];
+        const method = toOpenAPIMethod(fallbackContractConfig("defaultMethod", def.route.method));
+        const httpPath = toOpenAPIPath(def.route.path ?? toHttpPath(path));
+        const operationObjectRef = {
+          operationId,
+          summary: def.route.summary,
+          description: def.route.description,
+          deprecated: def.route.deprecated,
+          tags: def.route.tags?.map((tag) => tag)
+        };
+        this.#request(operationObjectRef, def);
+        this.#successResponse(operationObjectRef, def);
+        this.#errorResponse(operationObjectRef, def);
+        doc.paths ??= {};
+        doc.paths[httpPath] ??= {};
+        doc.paths[httpPath][method] = applyCustomOpenAPIOperation(operationObjectRef, contract);
+      } catch (e) {
+        if (!(e instanceof OpenAPIGeneratorError)) {
+          throw e;
+        }
+        errors.push(
+          `[OpenAPIGenerator] Error occurred while generating OpenAPI for procedure at path: ${operationId}
+${e.message}`
+        );
       }
-      return Object.keys(schema2).filter((key) => !NON_LOGIC_KEYWORDS.includes(key)).length === 0;
     });
-    return matches.length > 0;
+    if (errors.length) {
+      throw new OpenAPIGeneratorError(
+        `Some error occurred during OpenAPI generation:
+
+${errors.join("\n\n")}`
+      );
+    }
+    return this.serializer.serialize(doc)[0];
   }
-  separateObjectSchema(schema, separatedProperties) {
-    const matched = { ...schema };
-    const rest = { ...schema };
-    matched.properties = Object.entries(schema.properties ?? {}).filter(([key]) => separatedProperties.includes(key)).reduce((acc, [key, value]) => {
-      acc[key] = value;
-      return acc;
-    }, {});
-    matched.required = schema.required?.filter((key) => separatedProperties.includes(key));
-    matched.examples = schema.examples?.map((example) => {
-      if (!isObject(example)) {
-        return example;
+  #request(ref, def) {
+    const method = fallbackContractConfig("defaultMethod", def.route.method);
+    const details = getEventIteratorSchemaDetails(def.inputSchema);
+    if (details) {
+      ref.requestBody = {
+        required: true,
+        content: toOpenAPIEventIteratorContent(
+          this.converter.convert(details.yields, { strategy: "input" }),
+          this.converter.convert(details.returns, { strategy: "input" })
+        )
+      };
+      return;
+    }
+    const dynamicParams = getDynamicParams(def.route.path)?.map((v) => v.name);
+    const inputStructure = fallbackContractConfig("defaultInputStructure", def.route.inputStructure);
+    let [required, schema] = this.converter.convert(def.inputSchema, { strategy: "input" });
+    if (isAnySchema(schema) && !dynamicParams?.length) {
+      return;
+    }
+    if (inputStructure === "compact") {
+      if (dynamicParams?.length) {
+        const error2 = new OpenAPIGeneratorError(
+          'When input structure is "compact", and path has dynamic params, input schema must be an object with all dynamic params as required.'
+        );
+        if (!isObjectSchema(schema)) {
+          throw error2;
+        }
+        const [paramsSchema, rest] = separateObjectSchema(schema, dynamicParams);
+        schema = rest;
+        required = rest.required ? rest.required.length !== 0 : false;
+        if (!checkParamsSchema(paramsSchema, dynamicParams)) {
+          throw error2;
+        }
+        ref.parameters ??= [];
+        ref.parameters.push(...toOpenAPIParameters(paramsSchema, "path"));
       }
-      return Object.entries(example).reduce((acc, [key, value]) => {
-        if (separatedProperties.includes(key)) {
-          acc[key] = value;
+      if (method === "GET") {
+        if (!isObjectSchema(schema)) {
+          throw new OpenAPIGeneratorError(
+            'When method is "GET", input schema must satisfy: object | any | unknown'
+          );
         }
-        return acc;
-      }, {});
-    });
-    rest.properties = Object.entries(schema.properties ?? {}).filter(([key]) => !separatedProperties.includes(key)).reduce((acc, [key, value]) => {
-      acc[key] = value;
-      return acc;
-    }, {});
-    rest.required = schema.required?.filter((key) => !separatedProperties.includes(key));
-    rest.examples = schema.examples?.map((example) => {
-      if (!isObject(example)) {
-        return example;
+        ref.parameters ??= [];
+        ref.parameters.push(...toOpenAPIParameters(schema, "query"));
+      } else {
+        ref.requestBody = {
+          required,
+          content: toOpenAPIContent(schema)
+        };
       }
-      return Object.entries(example).reduce((acc, [key, value]) => {
-        if (!separatedProperties.includes(key)) {
-          acc[key] = value;
+      return;
+    }
+    const error = new OpenAPIGeneratorError(
+      'When input structure is "detailed", input schema must satisfy: { params?: Record<string, unknown>, query?: Record<string, unknown>, headers?: Record<string, unknown>, body?: unknown }'
+    );
+    if (!isObjectSchema(schema)) {
+      throw error;
+    }
+    if (dynamicParams?.length && (schema.properties?.params === void 0 || !isObjectSchema(schema.properties.params) || !checkParamsSchema(schema.properties.params, dynamicParams))) {
+      throw new OpenAPIGeneratorError(
+        'When input structure is "detailed" and path has dynamic params, the "params" schema must be an object with all dynamic params as required.'
+      );
+    }
+    for (const from of ["params", "query", "headers"]) {
+      const fromSchema = schema.properties?.[from];
+      if (fromSchema !== void 0) {
+        if (!isObjectSchema(fromSchema)) {
+          throw error;
         }
-        return acc;
-      }, {});
-    });
-    return [matched, rest];
+        const parameterIn = from === "params" ? "path" : from === "headers" ? "header" : "query";
+        ref.parameters ??= [];
+        ref.parameters.push(...toOpenAPIParameters(fromSchema, parameterIn));
+      }
+    }
+    if (schema.properties?.body !== void 0) {
+      ref.requestBody = {
+        required: schema.required?.includes("body"),
+        content: toOpenAPIContent(schema.properties.body)
+      };
+    }
   }
-  filterSchemaBranches(schema, check, matches = []) {
-    if (check(schema)) {
-      matches.push(schema);
-      return [matches, void 0];
+  #successResponse(ref, def) {
+    const outputSchema = def.outputSchema;
+    const status = fallbackContractConfig("defaultSuccessStatus", def.route.successStatus);
+    const description = fallbackContractConfig("defaultSuccessDescription", def.route?.successDescription);
+    const eventIteratorSchemaDetails = getEventIteratorSchemaDetails(outputSchema);
+    const outputStructure = fallbackContractConfig("defaultOutputStructure", def.route.outputStructure);
+    if (eventIteratorSchemaDetails) {
+      ref.responses ??= {};
+      ref.responses[status] = {
+        description,
+        content: toOpenAPIEventIteratorContent(
+          this.converter.convert(eventIteratorSchemaDetails.yields, { strategy: "output" }),
+          this.converter.convert(eventIteratorSchemaDetails.returns, { strategy: "output" })
+        )
+      };
+      return;
     }
-    if (typeof schema === "boolean") {
-      return [matches, schema];
+    const [_, json] = this.converter.convert(outputSchema, { strategy: "output" });
+    ref.responses ??= {};
+    ref.responses[status] = {
+      description
+    };
+    if (outputStructure === "compact") {
+      ref.responses[status].content = toOpenAPIContent(json);
+      return;
     }
-    if (schema.anyOf && Object.keys(schema).every(
-      (k) => k === "anyOf" || NON_LOGIC_KEYWORDS.includes(k)
-    )) {
-      const anyOf = schema.anyOf.map((s) => this.filterSchemaBranches(s, check, matches)[1]).filter((v) => !!v);
-      if (anyOf.length === 1 && typeof anyOf[0] === "object") {
-        return [matches, { ...schema, anyOf: void 0, ...anyOf[0] }];
-      }
-      return [matches, { ...schema, anyOf }];
+    const error = new OpenAPIGeneratorError(
+      'When output structure is "detailed", output schema must satisfy: { headers?: Record<string, unknown>, body?: unknown }'
+    );
+    if (!isObjectSchema(json)) {
+      throw error;
     }
-    if (schema.oneOf && Object.keys(schema).every(
-      (k) => k === "oneOf" || NON_LOGIC_KEYWORDS.includes(k)
-    )) {
-      const oneOf = schema.oneOf.map((s) => this.filterSchemaBranches(s, check, matches)[1]).filter((v) => !!v);
-      if (oneOf.length === 1 && typeof oneOf[0] === "object") {
-        return [matches, { ...schema, oneOf: void 0, ...oneOf[0] }];
+    if (json.properties?.headers !== void 0) {
+      if (!isObjectSchema(json.properties.headers)) {
+        throw error;
+      }
+      for (const key in json.properties.headers.properties) {
+        ref.responses[status].headers ??= {};
+        ref.responses[status].headers[key] = {
+          schema: toOpenAPISchema(json.properties.headers.properties[key]),
+          required: json.properties.headers.required?.includes(key)
+        };
       }
-      return [matches, { ...schema, oneOf }];
     }
-    return [matches, schema];
-  }
-}
-
-class OpenAPIGenerator {
-  contentBuilder;
-  parametersBuilder;
-  schemaConverter;
-  schemaUtils;
-  jsonSerializer;
-  pathParser;
-  inputStructureParser;
-  outputStructureParser;
-  errorHandlerStrategy;
-  ignoreUndefinedPathProcedures;
-  considerMissingTagDefinitionAsError;
-  strictErrorResponses;
-  constructor(options) {
-    this.parametersBuilder = options?.parametersBuilder ?? new OpenAPIParametersBuilder();
-    this.schemaConverter = new CompositeSchemaConverter(options?.schemaConverters ?? []);
-    this.schemaUtils = options?.schemaUtils ?? new SchemaUtils();
-    this.jsonSerializer = options?.jsonSerializer ?? new OpenAPIJsonSerializer();
-    this.contentBuilder = options?.contentBuilder ?? new OpenAPIContentBuilder(this.schemaUtils);
-    this.pathParser = new OpenAPIPathParser();
-    this.inputStructureParser = options?.inputStructureParser ?? new OpenAPIInputStructureParser(this.schemaConverter, this.schemaUtils, this.pathParser);
-    this.outputStructureParser = options?.outputStructureParser ?? new OpenAPIOutputStructureParser(this.schemaConverter, this.schemaUtils);
-    this.errorHandlerStrategy = options?.errorHandlerStrategy ?? "throw";
-    this.ignoreUndefinedPathProcedures = options?.ignoreUndefinedPathProcedures ?? false;
-    this.considerMissingTagDefinitionAsError = options?.considerMissingTagDefinitionAsError ?? false;
-    this.strictErrorResponses = options?.strictErrorResponses ?? true;
+    if (json.properties?.body !== void 0) {
+      ref.responses[status].content = toOpenAPIContent(json.properties.body);
+    }
   }
-  async generate(router, doc) {
-    const builder = new OpenApiBuilder({
-      ...doc,
-      openapi: "3.1.1"
-    });
-    const rootTags = doc.tags?.map((tag) => tag.name) ?? [];
-    await eachAllContractProcedure({
-      path: [],
-      router
-    }, ({ contract, path }) => {
-      try {
-        const def = contract["~orpc"];
-        if (this.ignoreUndefinedPathProcedures && def.route?.path === void 0) {
-          return;
-        }
-        const method = fallbackContractConfig("defaultMethod", def.route?.method);
-        const httpPath = def.route?.path ? toOpenAPI31RoutePattern(def.route?.path) : `/${path.map(encodeURIComponent).join("/")}`;
-        const { parameters, requestBody } = (() => {
-          const eventIteratorSchemaDetails = getEventIteratorSchemaDetails(def.inputSchema);
-          if (eventIteratorSchemaDetails) {
-            const requestBody3 = {
-              required: true,
-              content: {
-                "text/event-stream": {
-                  schema: {
-                    oneOf: [
-                      {
-                        type: "object",
-                        properties: {
-                          event: { type: "string", const: "message" },
-                          data: this.schemaConverter.convert(eventIteratorSchemaDetails.yields, { strategy: "input" }),
-                          id: { type: "string" },
-                          retry: { type: "number" }
-                        },
-                        required: ["event", "data"]
-                      },
-                      {
-                        type: "object",
-                        properties: {
-                          event: { type: "string", const: "done" },
-                          data: this.schemaConverter.convert(eventIteratorSchemaDetails.returns, { strategy: "input" }),
-                          id: { type: "string" },
-                          retry: { type: "number" }
-                        },
-                        required: ["event", "data"]
-                      },
-                      {
-                        type: "object",
-                        properties: {
-                          event: { type: "string", const: "error" },
-                          data: {},
-                          id: { type: "string" },
-                          retry: { type: "number" }
-                        },
-                        required: ["event", "data"]
-                      }
-                    ]
-                  }
-                }
-              }
-            };
-            return { requestBody: requestBody3, parameters: [] };
-          }
-          const inputStructure = fallbackContractConfig("defaultInputStructure", def.route?.inputStructure);
-          const { paramsSchema, querySchema, headersSchema, bodySchema } = this.inputStructureParser.parse(contract, inputStructure);
-          const params = paramsSchema ? this.parametersBuilder.build("path", paramsSchema, {
-            required: true
-          }) : [];
-          const query = querySchema ? this.parametersBuilder.build("query", querySchema) : [];
-          const headers = headersSchema ? this.parametersBuilder.build("header", headersSchema) : [];
-          const parameters2 = [...params, ...query, ...headers];
-          const requestBody2 = bodySchema !== void 0 ? {
-            required: this.schemaUtils.isUndefinableSchema(bodySchema),
-            content: this.contentBuilder.build(bodySchema)
-          } : void 0;
-          return { parameters: parameters2, requestBody: requestBody2 };
-        })();
-        const { responses } = (() => {
-          const eventIteratorSchemaDetails = getEventIteratorSchemaDetails(def.outputSchema);
-          if (eventIteratorSchemaDetails) {
-            const responses3 = {};
-            responses3[fallbackContractConfig("defaultSuccessStatus", def.route?.successStatus)] = {
-              description: fallbackContractConfig("defaultSuccessDescription", def.route?.successDescription),
-              content: {
-                "text/event-stream": {
-                  schema: {
-                    oneOf: [
-                      {
-                        type: "object",
-                        properties: {
-                          event: { type: "string", const: "message" },
-                          data: this.schemaConverter.convert(eventIteratorSchemaDetails.yields, { strategy: "input" }),
-                          id: { type: "string" },
-                          retry: { type: "number" }
-                        },
-                        required: ["event", "data"]
-                      },
-                      {
-                        type: "object",
-                        properties: {
-                          event: { type: "string", const: "done" },
-                          data: this.schemaConverter.convert(eventIteratorSchemaDetails.returns, { strategy: "input" }),
-                          id: { type: "string" },
-                          retry: { type: "number" }
-                        },
-                        required: ["event", "data"]
-                      },
-                      {
-                        type: "object",
-                        properties: {
-                          event: { type: "string", const: "error" },
-                          data: {},
-                          id: { type: "string" },
-                          retry: { type: "number" }
-                        },
-                        required: ["event", "data"]
-                      }
-                    ]
-                  }
-                }
-              }
-            };
-            return { responses: responses3 };
-          }
-          const outputStructure = fallbackContractConfig("defaultOutputStructure", def.route?.outputStructure);
-          const { headersSchema: resHeadersSchema, bodySchema: resBodySchema } = this.outputStructureParser.parse(contract, outputStructure);
-          const responses2 = {};
-          responses2[fallbackContractConfig("defaultSuccessStatus", def.route?.successStatus)] = {
-            description: fallbackContractConfig("defaultSuccessDescription", def.route?.successDescription),
-            content: resBodySchema !== void 0 ? this.contentBuilder.build(resBodySchema) : void 0,
-            headers: resHeadersSchema !== void 0 ? this.parametersBuilder.buildHeadersObject(resHeadersSchema) : void 0
-          };
-          return { responses: responses2 };
-        })();
-        const errors = group(Object.entries(def.errorMap ?? {}).filter(([_, config]) => config).map(([code, config]) => ({
-          ...config,
-          code,
-          status: fallbackORPCErrorStatus(code, config?.status)
-        })), (error) => error.status);
-        for (const status in errors) {
-          const configs = errors[status];
-          if (!configs || configs.length === 0) {
-            continue;
-          }
-          const schemas = configs.map(({ data, code, message }) => {
-            const json = {
-              type: "object",
-              properties: {
-                defined: { const: true },
-                code: { const: code },
-                status: { const: Number(status) },
-                message: { type: "string", default: message },
-                data: {}
-              },
-              required: ["defined", "code", "status", "message"]
-            };
-            if (data) {
-              const dataJson = this.schemaConverter.convert(data, { strategy: "output" });
-              json.properties.data = dataJson;
-              if (!this.schemaUtils.isUndefinableSchema(dataJson)) {
-                json.required.push("data");
-              }
-            }
-            return json;
-          });
-          if (this.strictErrorResponses) {
-            schemas.push({
+  #errorResponse(ref, def) {
+    const errorMap = def.errorMap;
+    const errors = {};
+    for (const code in errorMap) {
+      const config = errorMap[code];
+      if (!config) {
+        continue;
+      }
+      const status = fallbackORPCErrorStatus(code, config.status);
+      const message = fallbackORPCErrorMessage(code, config.message);
+      const [dataRequired, dataSchema] = this.converter.convert(config.data, { strategy: "output" });
+      errors[status] ??= [];
+      errors[status].push({
+        type: "object",
+        properties: {
+          defined: { const: true },
+          code: { const: code },
+          status: { const: status },
+          message: { type: "string", default: message },
+          data: dataSchema
+        },
+        required: dataRequired ? ["defined", "code", "status", "message", "data"] : ["defined", "code", "status", "message"]
+      });
+    }
+    ref.responses ??= {};
+    for (const status in errors) {
+      const schemas = errors[status];
+      ref.responses[status] = {
+        description: status,
+        content: toOpenAPIContent({
+          oneOf: [
+            ...schemas,
+            {
               type: "object",
               properties: {
                 defined: { const: false },
@@ -601,61 +508,16 @@ class OpenAPIGenerator {
                 data: {}
               },
               required: ["defined", "code", "status", "message"]
-            });
-          }
-          const contentSchema = schemas.length === 1 ? schemas[0] : {
-            oneOf: schemas
-          };
-          responses[status] = {
-            description: status,
-            content: this.contentBuilder.build(contentSchema)
-          };
-        }
-        if (this.considerMissingTagDefinitionAsError && def.route?.tags) {
-          const missingTag = def.route?.tags.find((tag) => !rootTags.includes(tag));
-          if (missingTag !== void 0) {
-            throw new OpenAPIError(
-              `Tag "${missingTag}" is missing definition. Please define it in OpenAPI root tags object`
-            );
-          }
-        }
-        const operation = {
-          summary: def.route?.summary,
-          description: def.route?.description,
-          deprecated: def.route?.deprecated,
-          tags: def.route?.tags ? [...def.route.tags] : void 0,
-          operationId: path.join("."),
-          parameters: parameters.length ? parameters : void 0,
-          requestBody,
-          responses
-        };
-        const extendedOperation = extendOperation(operation, contract);
-        builder.addPath(httpPath, {
-          [method.toLocaleLowerCase()]: extendedOperation
-        });
-      } catch (e) {
-        if (e instanceof OpenAPIError) {
-          const error = new OpenAPIError(`
-            Generate OpenAPI Error: ${e.message}
-            Happened at path: ${path.join(".")}
-          `, { cause: e });
-          if (this.errorHandlerStrategy === "throw") {
-            throw error;
-          }
-          if (this.errorHandlerStrategy === "log") {
-            console.error(error);
-          }
-        } else {
-          throw e;
-        }
-      }
-    });
-    return this.jsonSerializer.serialize(builder.getSpec())[0];
+            }
+          ]
+        })
+      };
+    }
   }
 }
 
 const oo = {
-  spec: setOperationExtender
+  spec: customOpenAPIOperation
 };
 
-export { CompositeSchemaConverter, NON_LOGIC_KEYWORDS, OpenAPIContentBuilder, OpenAPIGenerator, OpenAPIParametersBuilder, OpenAPIPathParser, SchemaUtils, extendOperation, getOperationExtender, oo, setOperationExtender, toOpenAPI31RoutePattern };
+export { CompositeSchemaConverter, LOGIC_KEYWORDS, OpenAPIGenerator, applyCustomOpenAPIOperation, checkParamsSchema, customOpenAPIOperation, filterSchemaBranches, getCustomOpenAPIOperation, isAnySchema, isFileSchema, isObjectSchema, oo, separateObjectSchema, toOpenAPIContent, toOpenAPIEventIteratorContent, toOpenAPIMethod, toOpenAPIParameters, toOpenAPIPath, toOpenAPISchema };