@xyd-js/openapi2opencli 0.0.0-canary-4287eee-20260630010340

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@xyd-js/openapi2opencli",
+  "version": "0.0.0-canary-4287eee-20260630010340",
+  "description": "Convert an OpenAPI 3.x document into an OpenCLI document (with the x-openapi request binding) consumable by the opencli2* code generators",
+  "main": "./dist/index.js",
+  "type": "module",
+  "dependencies": {
+    "openapi-types": "^12.1.3",
+    "@xyd-js/opencli": "0.1.0-build.0",
+    "@xyd-js/openapi": "0.0.0-canary-4287eee-20260630010340"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "rimraf": "^3.0.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "prebuild": "pnpm clean",
+    "build": "tsup",
+    "test": "vitest",
+    "ci:test": "vitest run",
+    "format": "bunx biome check --write src"
+  }
+}

package/src/action.ts

@@ -0,0 +1,118 @@
+import type { OpenAPIV3 } from 'openapi-types';
+
+import { kebabCase, splitWords } from './naming';
+import type { OpenApi2OpenCliOptions, VerbMap } from './types';
+import { DEFAULT_CUSTOM_ACTION_VERBS } from './types';
+
+export interface PathSegment {
+  kind: 'static' | 'param';
+  value: string;
+}
+
+/** Parse `/chat/completions/{completion_id}` into ordered segments. */
+export function parsePath(path: string): PathSegment[] {
+  return path
+    .split('/')
+    .filter(Boolean)
+    .map((seg) => {
+      const m = seg.match(/^\{(.+)\}$/);
+      return m ? { kind: 'param' as const, value: m[1] } : { kind: 'static' as const, value: seg };
+    });
+}
+
+export interface DerivedTarget {
+  /** kebab-cased resource command path, e.g. ["chat","completions"] */
+  resourcePath: string[];
+  /** kebab-cased leaf action, e.g. "create" / "retrieve" / "cancel" */
+  action: string;
+  /** optional aliases for the leaf command, e.g. ["get"] for retrieve */
+  aliases: string[];
+  /** wire names of path parameters in order (positional arguments) */
+  pathParamNames: string[];
+}
+
+const DEFAULT_VERBS: Required<VerbMap> = {
+  listCollection: 'list',
+  getItem: 'retrieve',
+  createCollection: 'create',
+  updateItem: 'update',
+  deleteItem: 'delete',
+};
+
+function leadingVerb(operationId?: string): string | undefined {
+  if (!operationId) return undefined;
+  return splitWords(operationId)[0];
+}
+
+/**
+ * Derive the command-tree placement of an operation from its method + path
+ * (the default "path" grouping). See the mapping table in the package README.
+ */
+export function deriveTarget(
+  method: string,
+  path: string,
+  operation: OpenAPIV3.OperationObject,
+  options: OpenApi2OpenCliOptions,
+): DerivedTarget {
+  const verbs: Required<VerbMap> = { ...DEFAULT_VERBS, ...(options.verbMap || {}) };
+  const customVerbs = new Set(
+    (options.customActionVerbs ?? DEFAULT_CUSTOM_ACTION_VERBS).map((v) => v.toLowerCase()),
+  );
+  const actionAliases = options.actionAliases !== false;
+
+  const segments = parsePath(path);
+  const staticSegs = segments.filter((s) => s.kind === 'static').map((s) => s.value);
+  const pathParamNames = segments.filter((s) => s.kind === 'param').map((s) => s.value);
+  const hasParams = pathParamNames.length > 0;
+  const last = segments[segments.length - 1];
+  const m = method.toLowerCase();
+
+  let resourceSegs: string[];
+  let action: string;
+  const aliases: string[] = [];
+
+  if (last && last.kind === 'param') {
+    // Item operation: /resource/{id}
+    resourceSegs = staticSegs;
+    if (m === 'get') {
+      action = verbs.getItem;
+      if (actionAliases && action === 'retrieve') aliases.push('get');
+    } else if (m === 'put' || m === 'patch') {
+      action = verbs.updateItem;
+    } else if (m === 'delete') {
+      action = verbs.deleteItem;
+    } else {
+      // POST on an item — uncommon; prefer the operationId verb.
+      action = leadingVerb(operation.operationId) || verbs.createCollection;
+    }
+  } else {
+    // Last segment is static.
+    const lastStatic = staticSegs[staticSegs.length - 1];
+    const isCustomAction = hasParams && lastStatic && customVerbs.has(lastStatic.toLowerCase());
+
+    if (isCustomAction) {
+      action = kebabCase(lastStatic);
+      resourceSegs = staticSegs.slice(0, -1);
+    } else {
+      resourceSegs = staticSegs;
+      if (m === 'get') {
+        action = verbs.listCollection;
+      } else if (m === 'post') {
+        action = verbs.createCollection;
+      } else if (m === 'put' || m === 'patch') {
+        action = verbs.updateItem;
+      } else if (m === 'delete') {
+        action = verbs.deleteItem;
+      } else {
+        action = leadingVerb(operation.operationId) || m;
+      }
+    }
+  }
+
+  return {
+    resourcePath: resourceSegs.map(kebabCase),
+    action: kebabCase(action),
+    aliases,
+    pathParamNames,
+  };
+}

package/src/body.ts

@@ -0,0 +1,132 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { Argument, Option, XOpenApiBody, XOpenApiBodyProp } from '@xyd-js/opencli';
+
+import { camelCase, kebabCase } from './naming';
+import {
+  arrayItems,
+  getEnum,
+  isArray,
+  isBinary,
+  isBoolean,
+  isObjectSchema,
+  resolveObjectSchema,
+  scalarType,
+  type Schema,
+} from './schema';
+import { uniqueName } from './unique';
+import type { FlagCase, OpenApi2OpenCliOptions } from './types';
+
+export interface BodyMapResult {
+  options: Option[];
+  xBody?: XOpenApiBody;
+}
+
+function flagName(wire: string, flagCase: FlagCase | undefined): string {
+  return flagCase === 'camel' ? camelCase(wire) : kebabCase(wire);
+}
+
+/** Pick the content type to drive the body mapping. */
+function pickContent(
+  content: { [media: string]: OpenAPIV3.MediaTypeObject } | undefined,
+): { mediaType: string; schema?: Schema } | undefined {
+  if (!content) return undefined;
+  const keys = Object.keys(content);
+  if (keys.length === 0) return undefined;
+  const prefer = ['application/json', 'multipart/form-data', 'application/x-www-form-urlencoded'];
+  const chosen = prefer.find((k) => keys.includes(k)) || keys[0];
+  return { mediaType: chosen, schema: content[chosen]?.schema as Schema | undefined };
+}
+
+/** Encoding hint a generator uses to serialize a CLI value into a body field. */
+function encodingFor(schema: Schema | undefined): XOpenApiBodyProp['encoding'] {
+  if (isBinary(schema)) return 'file';
+  if (isArray(schema)) return 'array';
+  const t = scalarType(schema);
+  if (t) return t as XOpenApiBodyProp['encoding'];
+  return 'json'; // nested object / oneOf / anyOf → JSON string
+}
+
+function valueArgument(schema: Schema | undefined): Argument {
+  if (isBinary(schema)) return { name: 'path' };
+  const isArr = isArray(schema);
+  const label = isArr
+    ? scalarType(arrayItems(schema)) || (isObjectSchema(arrayItems(schema)) ? 'json' : 'value')
+    : scalarType(schema) || (isObjectSchema(schema) ? 'json' : 'value');
+  const arg: Argument = { name: label };
+  const enumValues = getEnum(isArr ? arrayItems(schema) : schema);
+  if (enumValues) arg.acceptedValues = enumValues;
+  if (isArr) arg.arity = { minimum: 0 };
+  return arg;
+}
+
+/**
+ * Map an operation's request body to OpenCLI options + the `x-openapi.body`
+ * binding. With the default hybrid strategy, top-level scalars/scalar-arrays
+ * flatten into flags and nested objects/compositions collapse to a JSON-string
+ * flag named after the property.
+ */
+export function mapRequestBody(
+  requestBody: OpenAPIV3.RequestBodyObject | undefined,
+  usedFlagNames: Set<string>,
+  options: OpenApi2OpenCliOptions,
+): BodyMapResult {
+  if (!requestBody || !requestBody.content) return { options: [] };
+
+  const picked = pickContent(requestBody.content);
+  if (!picked) return { options: [] };
+
+  const { mediaType, schema } = picked;
+  const isMultipart = mediaType === 'multipart/form-data' || mediaType === 'application/x-www-form-urlencoded';
+  const bodyRequired = requestBody.required === true;
+
+  // Whole-body JSON flag (explicit "json" strategy or a non-object body).
+  const resolved = resolveObjectSchema(schema);
+  const useSingleJson = options.bodyStrategy === 'json' || (!resolved.object && !isMultipart);
+
+  if (useSingleJson) {
+    const name = uniqueName('body', usedFlagNames);
+    const opt: Option = {
+      name,
+      required: bodyRequired,
+      group: 'body',
+      description: requestBody.description || 'Request body as a JSON string',
+      arguments: [{ name: 'json' }],
+    };
+    return {
+      options: [opt],
+      xBody: { style: 'json', contentType: mediaType, from: `option:${name}`, properties: [] },
+    };
+  }
+
+  const object = resolved.object;
+  if (!object || !object.properties) {
+    return { options: [], xBody: { style: 'json', contentType: mediaType, properties: [] } };
+  }
+
+  const requiredSet = new Set<string>(Array.isArray(object.required) ? object.required : []);
+  const opts: Option[] = [];
+  const props: XOpenApiBodyProp[] = [];
+
+  for (const [wire, rawSchema] of Object.entries(object.properties)) {
+    // Skip internal markers injected by the dereferencer (e.g. __UNSAFE_refPath).
+    if (wire.startsWith('__')) continue;
+    const propSchema = rawSchema as Schema;
+    const name = uniqueName(flagName(wire, options.flagCase), usedFlagNames);
+    const required = requiredSet.has(wire);
+
+    const opt: Option = { name, group: 'body' };
+    if (required) opt.required = true;
+    if (propSchema.description) opt.description = propSchema.description;
+    if (!isBoolean(propSchema)) opt.arguments = [valueArgument(propSchema)];
+    opts.push(opt);
+
+    const prop: XOpenApiBodyProp = { name: wire, from: `option:${name}`, jsonPath: wire, encoding: encodingFor(propSchema) };
+    if (required) prop.required = true;
+    props.push(prop);
+  }
+
+  return {
+    options: opts,
+    xBody: { style: isMultipart ? 'multipart' : 'flatten', contentType: mediaType, properties: props },
+  };
+}

package/src/command.ts

@@ -0,0 +1,66 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { Command, XOpenApiCommand } from '@xyd-js/opencli';
+
+import { deriveTarget } from './action';
+import { mapParameters } from './parameters';
+import { mapRequestBody } from './body';
+import type { OpenApi2OpenCliOptions } from './types';
+
+/** Merge path-item parameters with operation parameters (operation wins on name+in). */
+function mergeParameters(
+  pathItemParams: OpenAPIV3.ParameterObject[],
+  operationParams: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[] | undefined,
+): OpenAPIV3.ParameterObject[] {
+  const byKey = new Map<string, OpenAPIV3.ParameterObject>();
+  const add = (p: OpenAPIV3.ParameterObject) => {
+    if (p && typeof p === 'object' && 'name' in p && 'in' in p) byKey.set(`${p.in}:${p.name}`, p);
+  };
+  for (const p of pathItemParams) add(p);
+  for (const p of (operationParams || []) as OpenAPIV3.ParameterObject[]) add(p);
+  return [...byKey.values()];
+}
+
+export interface BuiltLeaf {
+  resourcePath: string[];
+  command: Command;
+}
+
+/** Build a single leaf command (+ its resource placement) from one operation. */
+export function buildLeafCommand(
+  method: string,
+  path: string,
+  operation: OpenAPIV3.OperationObject,
+  pathItemParams: OpenAPIV3.ParameterObject[],
+  options: OpenApi2OpenCliOptions,
+): BuiltLeaf {
+  const target = deriveTarget(method, path, operation, options);
+  const allParams = mergeParameters(pathItemParams, operation.parameters);
+
+  const usedFlagNames = new Set<string>();
+  const params = mapParameters(allParams, target.pathParamNames, usedFlagNames, options);
+  const body = mapRequestBody(
+    operation.requestBody as OpenAPIV3.RequestBodyObject | undefined,
+    usedFlagNames,
+    options,
+  );
+
+  const command: Command = { name: target.action };
+  if (target.aliases.length) command.aliases = target.aliases;
+
+  const description = operation.summary || operation.description;
+  if (description) command.description = description;
+
+  if (params.arguments.length) command.arguments = params.arguments;
+
+  const allOptions = [...params.options, ...body.options];
+  if (allOptions.length) command.options = allOptions;
+
+  const xOpenapi: XOpenApiCommand = { method: method.toLowerCase(), path };
+  if (operation.operationId) xOpenapi.operationId = operation.operationId;
+  if (body.xBody?.contentType) xOpenapi.contentType = body.xBody.contentType;
+  if (params.xParams.length) xOpenapi.params = params.xParams;
+  if (body.xBody) xOpenapi.body = body.xBody;
+  command['x-openapi'] = xOpenapi;
+
+  return { resourcePath: target.resourcePath, command };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { openapi2opencli, openapi2opencliFromSource } from './openapi2opencli';
+export type {
+  OpenApi2OpenCliOptions,
+  VerbMap,
+  Grouping,
+  BodyStrategy,
+  FlagCase,
+} from './types';
+export { DEFAULT_CUSTOM_ACTION_VERBS } from './types';
+
+export { opencliToSurface, diffSurfaces } from './surface';
+export type { CliSurface, SurfaceCommand, SurfaceFlag, FlagKind, SurfaceDiff, Allowlist } from './surface';

package/src/naming.ts

@@ -0,0 +1,40 @@
+/**
+ * Split an identifier (camelCase, snake_case, kebab-case, space separated)
+ * into lowercase words.
+ */
+export function splitWords(input: string): string[] {
+  return input
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase boundary
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // ACRONYMBoundary
+    .split(/[\s_\-./]+/)
+    .map((w) => w.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/** kebab-case a wire name (e.g. `completionId` → `completion-id`, `max_tokens` → `max-tokens`). */
+export function kebabCase(input: string): string {
+  return splitWords(input).join('-');
+}
+
+/** camelCase a wire name. */
+export function camelCase(input: string): string {
+  const words = splitWords(input);
+  return words
+    .map((w, i) => (i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join('');
+}
+
+/** SCREAMING_SNAKE_CASE (used for env var names). */
+export function screamingSnakeCase(input: string): string {
+  return splitWords(input).join('_').toUpperCase();
+}
+
+/**
+ * Slugify a free-form title into a CLI binary name (lowercase, dash separated,
+ * alnum only). e.g. "OpenAI API" → "openai-api".
+ */
+export function slug(input: string): string {
+  return splitWords(input)
+    .join('-')
+    .replace(/[^a-z0-9-]/g, '');
+}

package/src/openapi2opencli.ts

@@ -0,0 +1,106 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { CliInfo, Contact, License, OpencliSpecJson, XOpenApiRoot } from '@xyd-js/opencli';
+import { deferencedOpenAPI } from '@xyd-js/openapi';
+
+import { buildLeafCommand } from './command';
+import { slug } from './naming';
+import { securitySchemesToXOpenApi } from './security';
+import { CommandTree } from './tree';
+import type { OpenApi2OpenCliOptions } from './types';
+
+// Mirrors SUPPORTED_HTTP_METHODS in @xyd-js/openapi (kept local to avoid a
+// brittle value import across the dist boundary).
+const DEFAULT_HTTP_METHODS: string[] = ['get', 'put', 'patch', 'post', 'delete'];
+
+function buildInfo(doc: OpenAPIV3.Document, cliName: string, version: string): CliInfo {
+  const info: CliInfo = { title: cliName, version };
+  const src = doc.info;
+  if (src?.description) info.description = src.description;
+  if ((src as { summary?: string })?.summary) info.summary = (src as { summary?: string }).summary;
+
+  if (src?.contact) {
+    const contact: Contact = {};
+    if (src.contact.name) contact.name = src.contact.name;
+    if (src.contact.url) contact.url = src.contact.url;
+    if (src.contact.email) contact.email = src.contact.email;
+    if (Object.keys(contact).length) info.contact = contact;
+  }
+
+  if (src?.license) {
+    const license: License = {};
+    if (src.license.name) license.name = src.license.name;
+    if ((src.license as { identifier?: string }).identifier)
+      license.identifier = (src.license as { identifier?: string }).identifier;
+    if (src.license.url) license.url = src.license.url;
+    if (Object.keys(license).length) info.license = license;
+  }
+
+  return info;
+}
+
+function buildXOpenApiRoot(doc: OpenAPIV3.Document, cliName: string, options: OpenApi2OpenCliOptions): XOpenApiRoot | undefined {
+  const servers = (doc.servers || []).map((s) => s.url).filter(Boolean);
+  const security = securitySchemesToXOpenApi(doc, cliName, options.authEnvVar);
+
+  const root: XOpenApiRoot = {};
+  if (servers.length) root.servers = servers;
+  if (security.length) root.security = security;
+  return Object.keys(root).length ? root : undefined;
+}
+
+/**
+ * Convert a (dereferenced) OpenAPI 3.x document into an OpenCLI document,
+ * embedding the `x-openapi` request binding on the root and on every command.
+ *
+ * Pure and synchronous — pass an already-dereferenced document
+ * (see {@link openapi2opencliFromSource} for the file/URL convenience).
+ */
+export function openapi2opencli(doc: OpenAPIV3.Document, options: OpenApi2OpenCliOptions = {}): OpencliSpecJson {
+  const cliName = options.cliName ?? (slug(doc.info?.title || 'cli') || 'cli');
+  const version = options.version ?? doc.info?.version ?? '0.0.0';
+  const methods = (options.includeMethods ?? DEFAULT_HTTP_METHODS).map((m) => m.toLowerCase());
+
+  const spec: OpencliSpecJson = {
+    opencli: '1.0.0',
+    info: buildInfo(doc, cliName, version),
+  };
+
+  const xRoot = buildXOpenApiRoot(doc, cliName, options);
+  if (xRoot) spec['x-openapi'] = xRoot;
+
+  const tree = new CommandTree();
+  const paths = doc.paths || {};
+
+  for (const [path, pathItem] of Object.entries(paths)) {
+    if (!pathItem) continue;
+    if (options.includePaths && !options.includePaths.some((p) => path.startsWith(p))) continue;
+
+    const pathItemParams = ((pathItem as OpenAPIV3.PathItemObject).parameters || []) as OpenAPIV3.ParameterObject[];
+
+    for (const method of methods) {
+      const operation = (pathItem as Record<string, unknown>)[method] as OpenAPIV3.OperationObject | undefined;
+      if (!operation || typeof operation !== 'object') continue;
+
+      const { resourcePath, command } = buildLeafCommand(method, path, operation, pathItemParams, options);
+      tree.insert(resourcePath, command);
+    }
+  }
+
+  const commands = tree.emit();
+  if (commands.length) spec.commands = commands;
+
+  return spec;
+}
+
+/**
+ * Read + dereference an OpenAPI spec from a file path or URL (via @xyd-js/openapi)
+ * then convert it to an OpenCLI document.
+ */
+export async function openapi2opencliFromSource(
+  source: string,
+  options: OpenApi2OpenCliOptions = {},
+): Promise<OpencliSpecJson> {
+  const doc = await deferencedOpenAPI(source);
+  if (!doc) throw new Error(`Failed to load OpenAPI spec from ${source}`);
+  return openapi2opencli(doc, options);
+}

package/src/parameters.ts

@@ -0,0 +1,108 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { Argument, Option, XOpenApiParam } from '@xyd-js/opencli';
+
+import { camelCase, kebabCase } from './naming';
+import { arrayItems, getEnum, isArray, isBoolean, isObjectSchema, scalarType, type Schema } from './schema';
+import { uniqueName } from './unique';
+import type { FlagCase, OpenApi2OpenCliOptions } from './types';
+
+/** Header parameters handled by the security layer — never surfaced as flags. */
+const AUTH_HEADERS = new Set(['authorization', 'x-api-key', 'api-key', 'openai-organization', 'openai-project']);
+
+export interface ParamMapResult {
+  arguments: Argument[];
+  options: Option[];
+  xParams: XOpenApiParam[];
+}
+
+function flagName(wire: string, flagCase: FlagCase | undefined): string {
+  return flagCase === 'camel' ? camelCase(wire) : kebabCase(wire);
+}
+
+/** A human-friendly value-argument label for an option (`--limit <integer>`). */
+function valueLabel(schema: Schema | undefined): string {
+  if (isArray(schema)) {
+    const item = arrayItems(schema);
+    return scalarType(item) || (isObjectSchema(item) ? 'json' : 'value');
+  }
+  return scalarType(schema) || (isObjectSchema(schema) ? 'json' : 'value');
+}
+
+/** Build the value Argument attached to a value-taking option. */
+function valueArgument(schema: Schema | undefined): Argument {
+  const arg: Argument = { name: valueLabel(schema) };
+  const enumValues = getEnum(isArray(schema) ? arrayItems(schema) : schema);
+  if (enumValues) arg.acceptedValues = enumValues;
+  if (isArray(schema)) {
+    // unbounded variadic: minimum 0, no maximum
+    arg.arity = { minimum: 0 };
+  }
+  return arg;
+}
+
+/**
+ * Map an operation's parameters (path/query/header/cookie) to OpenCLI arguments
+ * and options, recording the HTTP binding in `xParams`.
+ *
+ * @param params merged path-item + operation parameters (already dereferenced)
+ * @param pathParamOrder wire names of path params in path order (positional ordering)
+ * @param usedFlagNames shared flag-name allocator (also used by the body mapper)
+ */
+export function mapParameters(
+  params: OpenAPIV3.ParameterObject[],
+  pathParamOrder: string[],
+  usedFlagNames: Set<string>,
+  options: OpenApi2OpenCliOptions,
+): ParamMapResult {
+  const result: ParamMapResult = { arguments: [], options: [], xParams: [] };
+  const byName = new Map<string, OpenAPIV3.ParameterObject>();
+  for (const p of params) {
+    if (p && p.in === 'path') byName.set(p.name, p);
+  }
+
+  // Path params → positional arguments, in path order.
+  for (const wire of pathParamOrder) {
+    const p = byName.get(wire);
+    const schema = p?.schema as Schema | undefined;
+    const argName = kebabCase(wire);
+    const arg: Argument = { name: argName, required: true };
+    if (p?.description) arg.description = p.description;
+    const enumValues = getEnum(schema);
+    if (enumValues) arg.acceptedValues = enumValues;
+    result.arguments.push(arg);
+    result.xParams.push({ in: 'path', name: wire, from: `argument:${argName}`, required: true });
+  }
+
+  // Query / header / cookie params → options.
+  for (const p of params) {
+    if (!p || p.in === 'path') continue;
+    if (p.in === 'header' || p.in === 'cookie') {
+      if (!options.includeHeaders) continue;
+      if (AUTH_HEADERS.has(p.name.toLowerCase())) continue;
+    }
+
+    const schema = p.schema as Schema | undefined;
+    const name = uniqueName(flagName(p.name, options.flagCase), usedFlagNames);
+
+    const opt: Option = { name };
+    if (p.required) opt.required = true;
+    if (p.description) opt.description = p.description;
+    if (p.in !== 'query') opt.group = p.in; // 'query' is the default group; only annotate others
+    else opt.group = 'query';
+    if (p.in === 'header' || p.in === 'cookie') opt.hidden = true;
+
+    // boolean → flag with no value; everything else takes a value
+    if (!isBoolean(schema)) {
+      opt.arguments = [valueArgument(schema)];
+    }
+    result.options.push(opt);
+
+    const xParam: XOpenApiParam = { in: p.in, name: p.name, from: `option:${name}` };
+    if (p.required) xParam.required = true;
+    if (typeof (p as { explode?: boolean }).explode === 'boolean') xParam.explode = (p as { explode?: boolean }).explode;
+    if (typeof (p as { style?: string }).style === 'string') xParam.style = (p as { style?: string }).style;
+    result.xParams.push(xParam);
+  }
+
+  return result;
+}