- Added query and path parameter serialization from OpenAPI / Swagger

  metadata
  - Added support for array and object-style query parameters such as
  `deepObject`, `pipeDelimited`, and Swagger 2 collection formats
  - Added automatic API base URL detection from OAS `servers`
  - Added automatic API base URL detection from Swagger 2 `host`, `basePath`,
  and `schemes`
  - Added operation-level and path-level server overrides when the spec defines
  endpoint-specific targets

Author: snow-ghost

README.md

@@ -77,6 +77,18 @@ npx openapi-to-cli onboard \
 
 In practice this improves compatibility with APIs that define inputs outside simple path/query parameters, especially for `POST`, `PUT`, and `PATCH` operations.
 
+### Better request generation
+
+`ocli` now uses more request metadata from the specification when building real HTTP calls:
+
+- query and path parameter serialization from OpenAPI / Swagger metadata
+- support for array and object-style query parameters such as `deepObject`, `pipeDelimited`, and Swagger 2 collection formats
+- automatic API base URL detection from OAS `servers`
+- automatic API base URL detection from Swagger 2 `host`, `basePath`, and `schemes`
+- operation-level and path-level server overrides when the spec defines different targets for different endpoints
+
+In practice this reduces the amount of manual profile setup and improves compatibility with APIs that rely on non-trivial parameter encoding or per-operation server definitions.
+
 ### Command search
 
 ```bash

src/cli.ts

@@ -34,7 +34,7 @@ const defaultHttpClient: HttpClient = {
 };
 
 interface AddProfileArgs {
-  "api-base-url": string;
+  "api-base-url"?: string;
   "openapi-spec": string;
   "api-basic-auth"?: string;
   "api-bearer-token"?: string;
@@ -229,26 +229,25 @@ function buildRequestUrl(profile: Profile, command: CliCommand, flags: Record<st
       const value = flags[opt.name];
       if (value !== undefined) {
         const token = `{${opt.name}}`;
-        pathValue = pathValue.replace(token, encodeURIComponent(value));
+        pathValue = pathValue.replace(token, serializePathParameter(opt, value));
       }
     });
 
-  const baseUrl = profile.apiBaseUrl.replace(/\/+$/, "");
-  let url = `${baseUrl}${pathValue}`;
+  const baseUrl = (command.serverUrl ?? profile.apiBaseUrl).replace(/\/+$/, "");
+  let url = baseUrl ? `${baseUrl}${pathValue}` : pathValue;
 
-  const queryParams = new URLSearchParams();
+  const queryParts: string[] = [];
   command.options
     .filter((opt) => opt.location === "query")
     .forEach((opt) => {
       const value = flags[opt.name];
       if (value !== undefined) {
-        queryParams.set(opt.name, value);
+        queryParts.push(...serializeQueryParameter(opt, value));
       }
     });
 
-  const queryString = queryParams.toString();
-  if (queryString) {
-    url += url.includes("?") ? `&${queryString}` : `?${queryString}`;
+  if (queryParts.length > 0) {
+    url += url.includes("?") ? `&${queryParts.join("&")}` : `?${queryParts.join("&")}`;
   }
 
   return url;
@@ -351,6 +350,164 @@ function buildRequestPayload(
   return {};
 }
 
+function serializePathParameter(option: CliCommandOption, rawValue: string): string {
+  const value = parseStructuredParameterValue(option, rawValue);
+
+  if (Array.isArray(value)) {
+    const encoded = value.map((item) => encodeURIComponent(String(item)));
+    const style = option.style ?? "simple";
+    const explode = option.explode ?? false;
+
+    if (style === "label") {
+      return explode ? `.${encoded.join(".")}` : `.${encoded.join(",")}`;
+    }
+
+    if (style === "matrix") {
+      return explode
+        ? encoded.map((item) => `;${encodeURIComponent(option.name)}=${item}`).join("")
+        : `;${encodeURIComponent(option.name)}=${encoded.join(",")}`;
+    }
+
+    return encoded.join(",");
+  }
+
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).map(
+      ([key, item]) => [encodeURIComponent(key), encodeURIComponent(String(item))] as const
+    );
+    const style = option.style ?? "simple";
+    const explode = option.explode ?? false;
+
+    if (style === "label") {
+      return explode
+        ? `.${entries.map(([key, item]) => `${key}=${item}`).join(".")}`
+        : `.${entries.flat().join(",")}`;
+    }
+
+    if (style === "matrix") {
+      return explode
+        ? entries.map(([key, item]) => `;${key}=${item}`).join("")
+        : `;${encodeURIComponent(option.name)}=${entries.flat().join(",")}`;
+    }
+
+    return explode
+      ? entries.map(([key, item]) => `${key}=${item}`).join(",")
+      : entries.flat().join(",");
+  }
+
+  return encodeURIComponent(String(value));
+}
+
+function serializeQueryParameter(option: CliCommandOption, rawValue: string): string[] {
+  const value = parseStructuredParameterValue(option, rawValue);
+  const encodedName = encodeURIComponent(option.name);
+
+  if (Array.isArray(value)) {
+    const encodedValues = value.map((item) => encodeURIComponent(String(item)));
+
+    if (option.collectionFormat === "multi") {
+      return encodedValues.map((item) => `${encodedName}=${item}`);
+    }
+
+    const joiner = option.collectionFormat === "ssv"
+      ? " "
+      : option.collectionFormat === "tsv"
+        ? "\t"
+        : option.collectionFormat === "pipes"
+          ? "|"
+          : option.style === "spaceDelimited"
+            ? " "
+            : option.style === "pipeDelimited"
+              ? "|"
+              : ",";
+
+    const explode = option.collectionFormat
+      ? option.collectionFormat === "multi"
+      : option.explode ?? true;
+
+    if (explode && joiner === ",") {
+      return encodedValues.map((item) => `${encodedName}=${item}`);
+    }
+
+    return [`${encodedName}=${encodedValues.join(encodeURIComponent(joiner))}`];
+  }
+
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).map(
+      ([key, item]) => [encodeURIComponent(key), encodeURIComponent(String(item))] as const
+    );
+    const style = option.style ?? "form";
+    const explode = option.explode ?? true;
+
+    if (style === "deepObject") {
+      return entries.map(([key, item]) => `${encodedName}%5B${key}%5D=${item}`);
+    }
+
+    if (explode) {
+      return entries.map(([key, item]) => `${key}=${item}`);
+    }
+
+    return [`${encodedName}=${entries.flat().join(",")}`];
+  }
+
+  return [`${encodedName}=${encodeURIComponent(String(value))}`];
+}
+
+function parseStructuredParameterValue(option: CliCommandOption, rawValue: string): unknown {
+  if (option.schemaType === "array") {
+    const trimmed = rawValue.trim();
+    if (trimmed.startsWith("[")) {
+      return parseBodyFlagValue(rawValue);
+    }
+    return rawValue.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+  }
+
+  if (option.schemaType === "object") {
+    const trimmed = rawValue.trim();
+    if (!trimmed.startsWith("{")) {
+      throw new Error(`Object parameter --${option.name} expects JSON object value`);
+    }
+    return parseBodyFlagValue(rawValue);
+  }
+
+  return rawValue;
+}
+
+function deriveApiBaseUrlFromSpec(spec: unknown): string {
+  if (!spec || typeof spec !== "object") {
+    return "";
+  }
+
+  const record = spec as Record<string, unknown>;
+  const servers = record.servers;
+  if (Array.isArray(servers) && servers.length > 0) {
+    const server = servers[0] as Record<string, unknown>;
+    if (typeof server?.url === "string" && server.url.length > 0) {
+      let url = server.url;
+      const variables = server.variables as Record<string, { default?: string }> | undefined;
+      if (variables) {
+        Object.entries(variables).forEach(([name, variable]) => {
+          url = url.replace(new RegExp(`\\{${name}\\}`, "g"), variable?.default ?? "");
+        });
+      }
+      if (/^https?:\/\//i.test(url)) {
+        return url.replace(/\/+$/, "");
+      }
+    }
+  }
+
+  const host = typeof record.host === "string" ? record.host : "";
+  if (!host) {
+    return "";
+  }
+
+  const schemes = Array.isArray(record.schemes) && record.schemes.length > 0
+    ? record.schemes as string[]
+    : ["https"];
+  const basePath = typeof record.basePath === "string" ? record.basePath : "";
+  return `${schemes[0]}://${host}${basePath}`.replace(/\/+$/, "");
+}
+
 export async function run(argv: string[], options?: RunOptions): Promise<void> {
   const cwd = options?.cwd ?? process.cwd();
   const configLocator = options?.configLocator ?? new ConfigLocator();
@@ -394,7 +551,7 @@ export async function run(argv: string[], options?: RunOptions): Promise<void> {
 
     const profile: Profile = {
       name: profileName,
-      apiBaseUrl: args["api-base-url"],
+      apiBaseUrl: args["api-base-url"] ?? "",
       apiBasicAuth: args["api-basic-auth"] ?? "",
       apiBearerToken: args["api-bearer-token"] ?? "",
       openapiSpecSource: args["openapi-spec"],
@@ -405,13 +562,21 @@ export async function run(argv: string[], options?: RunOptions): Promise<void> {
       customHeaders,
     };
 
-    await openapiLoader.loadSpec(profile, { refresh: true });
+    const spec = await openapiLoader.loadSpec(profile, { refresh: true });
+    profile.apiBaseUrl = profile.apiBaseUrl || deriveApiBaseUrlFromSpec(spec);
+    if (!profile.apiBaseUrl) {
+      throw new Error("Unable to determine API base URL. Provide --api-base-url explicitly.");
+    }
     profileStore.saveProfile(cwd, profile, { makeCurrent: true });
   };
 
   const addProfileOptions = (y: ReturnType<typeof yargs>) =>
     y
-      .option("api-base-url", { type: "string", demandOption: true })
+      .option("api-base-url", {
+        type: "string",
+        demandOption: false,
+        description: "Base URL for API requests. If omitted, derived from spec servers/host/basePath when possible.",
+      })
       .option("openapi-spec", { type: "string", demandOption: true })
       .option("api-basic-auth", { type: "string", default: "" })
       .option("api-bearer-token", { type: "string", default: "" })