Add multi-file specs and richer help support

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.
 
+
+### Multi-file specs and richer help
+
+`ocli` now works better with larger, more structured API descriptions:
+
+- external `$ref` resolution across multiple local or remote OpenAPI / Swagger documents
+- support for multi-document specs that split paths, parameters, and request bodies into separate files
+- richer `--help` output with schema hints such as `enum`, `default`, `nullable`, and `oneOf`
+- better handling of composed schemas that use `allOf` for shared request object structure
+
+In practice this improves compatibility with modular specs and makes generated commands easier to use without opening the original OpenAPI document.
+
 ### Command search
 
 ```bash

src/cli.ts

@@ -97,7 +97,21 @@ async function runApiCommand(
       } else if (baseType === "boolean") {
         typeLabel = "boolean";
       }
-      const descriptionPart = opt.description ?? "";
+      const hintParts: string[] = [];
+      if (opt.enumValues && opt.enumValues.length > 0) {
+        hintParts.push(`enum: ${opt.enumValues.join(", ")}`);
+      }
+      if (opt.defaultValue !== undefined) {
+        hintParts.push(`default: ${opt.defaultValue}`);
+      }
+      if (opt.nullable) {
+        hintParts.push("nullable");
+      }
+      if (opt.oneOfTypes && opt.oneOfTypes.length > 0) {
+        hintParts.push(`oneOf: ${opt.oneOfTypes.join(" | ")}`);
+      }
+
+      const descriptionPart = [opt.description ?? "", ...hintParts].filter(Boolean).join("; ");
       const descPrefix = opt.required ? "(required)" : "(optional)";
       const desc = descriptionPart ? `${descPrefix} ${descriptionPart}` : descPrefix;
 

src/openapi-loader.ts

@@ -36,7 +36,7 @@ export class OpenapiLoader {
       return JSON.parse(cached);
     }
 
-    const spec = await this.loadFromSource(profile.openapiSpecSource);
+    const spec = await this.loadAndResolveSpec(profile.openapiSpecSource);
     this.ensureCacheDir(cachePath);
 
     const serialized = JSON.stringify(spec, null, 2);
@@ -45,6 +45,17 @@ export class OpenapiLoader {
     return spec;
   }
 
+  private async loadAndResolveSpec(source: string): Promise<unknown> {
+    const rawDocCache = new Map<string, unknown>();
+    const root = await this.loadDocument(source, rawDocCache);
+    return this.resolveRefs(root, {
+      currentSource: source,
+      currentDocument: root,
+      rawDocCache,
+      resolvingRefs: new Set<string>(),
+    });
+  }
+
   private async loadFromSource(source: string): Promise<unknown> {
     if (source.startsWith("http://") || source.startsWith("https://")) {
       const response = await axios.get(source, { responseType: "text" });
@@ -55,6 +66,16 @@ export class OpenapiLoader {
     return this.parseSpec(raw, source);
   }
 
+  private async loadDocument(source: string, rawDocCache: Map<string, unknown>): Promise<unknown> {
+    if (rawDocCache.has(source)) {
+      return rawDocCache.get(source);
+    }
+
+    const loaded = await this.loadFromSource(source);
+    rawDocCache.set(source, loaded);
+    return loaded;
+  }
+
   private parseSpec(content: string | object, source: string): unknown {
     if (typeof content !== "string") {
       return content;
@@ -65,6 +86,128 @@ export class OpenapiLoader {
     return JSON.parse(content);
   }
 
+  private async resolveRefs(
+    value: unknown,
+    context: {
+      currentSource: string;
+      currentDocument: unknown;
+      rawDocCache: Map<string, unknown>;
+      resolvingRefs: Set<string>;
+    }
+  ): Promise<unknown> {
+    if (Array.isArray(value)) {
+      const items = await Promise.all(value.map((item) => this.resolveRefs(item, context)));
+      return items;
+    }
+
+    if (!value || typeof value !== "object") {
+      return value;
+    }
+
+    const record = value as Record<string, unknown>;
+    const ref = record.$ref;
+
+    if (typeof ref === "string") {
+      const siblingEntries = Object.entries(record).filter(([key]) => key !== "$ref");
+      const resolvedRef = await this.resolveRef(ref, context);
+      const resolvedSiblings = Object.fromEntries(
+        await Promise.all(
+          siblingEntries.map(async ([key, siblingValue]) => [key, await this.resolveRefs(siblingValue, context)] as const)
+        )
+      );
+
+      if (resolvedRef && typeof resolvedRef === "object" && !Array.isArray(resolvedRef)) {
+        return {
+          ...(resolvedRef as Record<string, unknown>),
+          ...resolvedSiblings,
+        };
+      }
+
+      return Object.keys(resolvedSiblings).length > 0 ? resolvedSiblings : resolvedRef;
+    }
+
+    const resolvedEntries = await Promise.all(
+      Object.entries(record).map(async ([key, nested]) => [key, await this.resolveRefs(nested, context)] as const)
+    );
+    return Object.fromEntries(resolvedEntries);
+  }
+
+  private async resolveRef(
+    ref: string,
+    context: {
+      currentSource: string;
+      currentDocument: unknown;
+      rawDocCache: Map<string, unknown>;
+      resolvingRefs: Set<string>;
+    }
+  ): Promise<unknown> {
+    const { source, pointer } = this.splitRef(ref, context.currentSource);
+    const cacheKey = `${source}#${pointer}`;
+
+    if (context.resolvingRefs.has(cacheKey)) {
+      return { $ref: ref };
+    }
+
+    context.resolvingRefs.add(cacheKey);
+
+    const targetDocument = source === context.currentSource
+      ? context.currentDocument
+      : await this.loadDocument(source, context.rawDocCache);
+
+    const targetValue = this.resolvePointer(targetDocument, pointer);
+    const resolvedValue = await this.resolveRefs(targetValue, {
+      currentSource: source,
+      currentDocument: targetDocument,
+      rawDocCache: context.rawDocCache,
+      resolvingRefs: context.resolvingRefs,
+    });
+
+    context.resolvingRefs.delete(cacheKey);
+    return resolvedValue;
+  }
+
+  private splitRef(ref: string, currentSource: string): { source: string; pointer: string } {
+    const [refSource, pointer = ""] = ref.split("#", 2);
+    if (!refSource) {
+      return { source: currentSource, pointer };
+    }
+
+    if (refSource.startsWith("http://") || refSource.startsWith("https://")) {
+      return { source: refSource, pointer };
+    }
+
+    if (currentSource.startsWith("http://") || currentSource.startsWith("https://")) {
+      return { source: new URL(refSource, currentSource).toString(), pointer };
+    }
+
+    return { source: path.resolve(path.dirname(currentSource), refSource), pointer };
+  }
+
+  private resolvePointer(document: unknown, pointer: string): unknown {
+    if (!pointer) {
+      return document;
+    }
+
+    if (!pointer.startsWith("/")) {
+      return document;
+    }
+
+    const parts = pointer
+      .slice(1)
+      .split("/")
+      .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
+
+    let current: unknown = document;
+    for (const part of parts) {
+      if (!current || typeof current !== "object" || !(part in (current as Record<string, unknown>))) {
+        return undefined;
+      }
+      current = (current as Record<string, unknown>)[part];
+    }
+
+    return current;
+  }
+
   private isYamlSource(source: string): boolean {
     const lower = source.toLowerCase().split("?")[0];
     return lower.endsWith(".yaml") || lower.endsWith(".yml");