@askills/openapi-explorer-cli 0.0.1

package/README.md

@@ -0,0 +1,93 @@
+# OpenAPI Explorer CLI
+
+CLI tool for progressive exploration of OpenAPI/Swagger API documentation. Load a spec from URL or local file and inspect endpoints, schemas, tags — all in one command, no state, no server.
+
+Part of the `admin-skills` monorepo.
+
+## Quick Start
+
+Requires Node.js >= 22.18 (TypeScript is run natively via Node's built-in
+type-stripping — no compiler or loader needed).
+
+```bash
+# run without installing
+npx @askills/openapi-explorer-cli info https://petstore.swagger.io/v2/swagger.json
+
+# or install globally
+npm install -g @askills/openapi-explorer-cli
+openapi-explorer info https://petstore.swagger.io/v2/swagger.json
+```
+
+## Commands
+
+| Command                                               | Description                                              |
+| ----------------------------------------------------- | -------------------------------------------------------- |
+| `info <source>`                                       | API overview: title, version, endpoint/schema/tag counts |
+| `tags <source>`                                       | List tag groups with endpoint counts                     |
+| `paths <source> [--tag <t>] [--limit N] [--offset N]` | List endpoints, filtered by tag, with pagination         |
+| `endpoint <source> <path> <method> [--full]`          | Endpoint detail. `--full` resolves all `$ref`            |
+| `schemas <source> [--limit N] [--offset N]`           | List component schemas with pagination                   |
+| `schema <source> <schema_name>`                       | Schema detail with properties, types, constraints        |
+| `search <source> <query>`                             | Full-text search across endpoints, schemas, properties   |
+
+`<source>` is a URL (`https://...`) or local file path — auto-detected.
+
+## Progressive Exploration Workflow
+
+```
+1. info <source>               → overview of the API
+2. tags <source>                → see available groups
+3. paths <source> --tag users   → browse endpoints in a group
+4. endpoint <source> <path> <method> --full  → drill into endpoint
+5. schemas <source>             → see available data models
+6. schema <source> <name>       → inspect a model
+7. search <source> <query>      → find anything across the spec
+```
+
+## Examples
+
+```bash
+node src/main.ts info https://petstore.swagger.io/v2/swagger.json
+node src/main.ts tags ./spec.json
+node src/main.ts paths ./spec.json --tag pets --limit 10
+node src/main.ts schemas ./spec.json --limit 5
+node src/main.ts schema ./spec.json Config
+node src/main.ts endpoint ./spec.json /pets/{petId} get --full
+node src/main.ts search ./spec.json "payment"
+```
+
+## Development
+
+Requires Node.js 22+ (native TypeScript). No build step needed.
+
+```bash
+pnpm install
+pnpm test
+pnpm start info <source>
+```
+
+The source is TypeScript at `src/`, organized by module:
+
+```
+src/
+├── main.ts                  # Entry point
+├── types.ts                 # Shared types
+├── cli/args.ts              # Argument parsing
+├── cli/dispatch.ts          # Command routing
+├── commands/                # One file per command
+├── core/loader.ts           # Spec loading (URL/file)
+├── core/queries.ts          # Query functions
+├── core/resolve.ts          # $ref resolution
+└── formatters/              # Schema & endpoint formatting
+```
+
+## Compatibility
+
+- OpenAPI v3.x, Swagger v2
+- JSON format only (YAML not supported)
+- Remote URLs and local file paths
+- Node.js 22+ (native TypeScript support required)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@askills/openapi-explorer-cli",
+  "version": "0.0.1",
+  "description": "CLI for progressive exploration of OpenAPI/Swagger API documentation",
+  "type": "module",
+  "license": "MIT",
+  "author": "anuoua",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anuoua/skills.git",
+    "directory": "packages/openapi-explorer-cli"
+  },
+  "bin": {
+    "openapi-explorer": "src/main.ts"
+  },
+  "scripts": {
+    "start": "node src/main.ts",
+    "test": "node --test test/*.test.ts",
+    "test:watch": "node --test --watch test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0"
+  }
+}

package/src/cli/args.ts

@@ -0,0 +1,59 @@
+export function parseArgs(argv: string[]): {
+  command: string;
+  source: string;
+  flags: Record<string, string | boolean | number>;
+  positional: string[];
+} {
+  const args = argv.slice(2);
+  if (!args.length || args[0] === "--help" || args[0] === "-h") {
+    return { command: "help", source: "", flags: {}, positional: [] };
+  }
+
+  const command = args[0] ?? "";
+  const source = args[1] ?? "";
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean | number> = {};
+
+  let i = 2;
+  while (i < args.length) {
+    const arg = args[i]!;
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (key === "full") {
+        flags[key] = true;
+        i++;
+      } else if (key === "tag" || key === "limit" || key === "offset") {
+        flags[key] = args[i + 1] ?? "";
+        i += 2;
+      } else {
+        flags[key] = args[i + 1] ?? true;
+        i += 2;
+      }
+    } else {
+      positional.push(arg);
+      i++;
+    }
+  }
+
+  return { command, source, flags, positional };
+}
+
+export function printHelp(): string {
+  return `Usage: openapi-explorer <command> <source> [args...]
+
+source can be a URL (https://...) or a local file path.
+
+Commands:
+  info <source>                          API overview
+  tags <source>                          List tag groups
+  paths <source> [--tag <t>] [--limit N] [--offset N]   List endpoints
+  endpoint <source> <path> <method> [--full]             Endpoint detail
+  schemas <source> [--limit N] [--offset N]              List schemas
+  schema <source> <schema_name>                           Schema detail
+  search <source> <query>                                 Full-text search
+
+Examples:
+  openapi-explorer info https://petstore.swagger.io/v2/swagger.json
+  openapi-explorer endpoint ./spec.json /pets/{petId} get --full
+  openapi-explorer paths ./spec.json --tag pets`;
+}

package/src/cli/dispatch.ts

@@ -0,0 +1,80 @@
+import { cmdInfo } from "../commands/info.ts";
+import { cmdTags } from "../commands/tags.ts";
+import { cmdPaths } from "../commands/paths.ts";
+import { cmdEndpoint } from "../commands/endpoint.ts";
+import { cmdSchemas } from "../commands/schemas.ts";
+import { cmdSchema } from "../commands/schema.ts";
+import { cmdSearch } from "../commands/search.ts";
+import { parseArgs, printHelp } from "./args.ts";
+
+export async function dispatch(argv: string[]): Promise<string> {
+  const { command, source, flags, positional } = parseArgs(argv);
+
+  switch (command) {
+    case "help":
+      return printHelp();
+
+    case "info":
+      if (!source) throw new Error("Usage: swagger.mjs info <source>");
+      return await cmdInfo(source);
+
+    case "tags":
+      if (!source) throw new Error("Usage: swagger.mjs tags <source>");
+      return await cmdTags(source);
+
+    case "paths": {
+      if (!source)
+        throw new Error(
+          "Usage: swagger.mjs paths <source> [--tag <t>] [--limit N] [--offset N]",
+        );
+      const tag = typeof flags.tag === "string" ? flags.tag : undefined;
+      const limit =
+        typeof flags.limit === "string" ? parseInt(flags.limit, 10) || 50 : 50;
+      const offset =
+        typeof flags.offset === "string" ? parseInt(flags.offset, 10) || 0 : 0;
+      return await cmdPaths(source, tag, limit, offset);
+    }
+
+    case "endpoint":
+    case "ep": {
+      const path = positional[0] || flags.path;
+      const method = positional[1] || flags.method;
+      if (!source || !path || !method) {
+        throw new Error(
+          "Usage: swagger.mjs endpoint <source> <path> <method> [--full]",
+        );
+      }
+      const full = flags.full === true;
+      return await cmdEndpoint(source, path as string, method as string, full);
+    }
+
+    case "schemas": {
+      if (!source)
+        throw new Error(
+          "Usage: swagger.mjs schemas <source> [--limit N] [--offset N]",
+        );
+      const slimit =
+        typeof flags.limit === "string" ? parseInt(flags.limit, 10) || 50 : 50;
+      const soffset =
+        typeof flags.offset === "string" ? parseInt(flags.offset, 10) || 0 : 0;
+      return await cmdSchemas(source, slimit, soffset);
+    }
+
+    case "schema": {
+      const schemaName = positional[0] || flags.name;
+      if (!source || !schemaName)
+        throw new Error("Usage: swagger.mjs schema <source> <schema_name>");
+      return await cmdSchema(source, schemaName as string);
+    }
+
+    case "search": {
+      const query = positional[0] || flags.query;
+      if (!source || !query)
+        throw new Error("Usage: swagger.mjs search <source> <query>");
+      return await cmdSearch(source, query as string);
+    }
+
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}

package/src/commands/endpoint.ts

@@ -0,0 +1,104 @@
+import { loadSpec } from "../core/loader.ts";
+import { getEndpoints, getPathParams } from "../core/queries.ts";
+import { deepResolve } from "../core/resolve.ts";
+import { fmtEndpoint } from "../formatters/endpoint.ts";
+import type { FormattedEndpoint } from "../types.ts";
+
+export async function cmdEndpoint(
+  source: string,
+  path: string,
+  method: string,
+  full = false,
+): Promise<string> {
+  const spec = await loadSpec(source);
+  method = method.toLowerCase();
+  const op = spec.paths[path]?.[method];
+  if (!op) {
+    const similar = getEndpoints(spec)
+      .filter((e) => e.path.includes(path) || path.includes(e.path))
+      .slice(0, 5);
+    const hint = similar.length
+      ? "\n\nDid you mean?\n" +
+        similar.map((e) => `  ${e.method.toUpperCase()} ${e.path}`).join("\n")
+      : "";
+    throw new Error(`No ${method.toUpperCase()} ${path} found.${hint}`);
+  }
+
+  const paramNames = getPathParams(path);
+  const mergedParams = [
+    ...paramNames.map(
+      (n) =>
+        (op.parameters || []).find((p: any) => p.name === n) || {
+          name: n,
+          in: "path",
+          required: true,
+          description: `Path param: ${n}`,
+          schema: { type: "string" },
+        },
+    ),
+    ...(op.parameters || []).filter((p: any) => !paramNames.includes(p.name)),
+  ];
+
+  const ep: FormattedEndpoint = {
+    path,
+    method,
+    summary: op.summary,
+    description: op.description,
+    operationId: op.operationId,
+    tags: op.tags || [],
+    deprecated: op.deprecated || false,
+    parameters: full
+      ? mergedParams.map((p: any) => ({
+          ...p,
+          schema: p.schema ? deepResolve(p.schema, spec) : p.schema,
+        }))
+      : mergedParams,
+    requestBody: op.requestBody
+      ? {
+          description: op.requestBody.description,
+          required: op.requestBody.required,
+          content: Object.fromEntries(
+            Object.entries(op.requestBody.content).map(
+              ([ct, mt]: [string, any]) => [
+                ct,
+                {
+                  schema:
+                    full && mt.schema
+                      ? deepResolve(mt.schema, spec)
+                      : mt.schema,
+                },
+              ],
+            ),
+          ),
+        }
+      : undefined,
+    responses: op.responses
+      ? Object.fromEntries(
+          Object.entries(op.responses).map(([code, resp]: [string, any]) => [
+            code,
+            {
+              description: resp.description,
+              content: resp.content
+                ? Object.fromEntries(
+                    Object.entries(resp.content).map(
+                      ([ct, mt]: [string, any]) => [
+                        ct,
+                        {
+                          schema:
+                            full && mt.schema
+                              ? deepResolve(mt.schema, spec)
+                              : mt.schema,
+                        },
+                      ],
+                    ),
+                  )
+                : undefined,
+            },
+          ]),
+        )
+      : undefined,
+    security: op.security,
+  };
+
+  return fmtEndpoint(ep);
+}

package/src/commands/info.ts

@@ -0,0 +1,44 @@
+import type { OpenAPISpec } from "../types.ts";
+import { loadSpec, getServerUrl } from "../core/loader.ts";
+import { getEndpoints, getSchemas, getTags } from "../core/queries.ts";
+
+export async function cmdInfo(source: string): Promise<string> {
+  const spec = await loadSpec(source);
+  const eps = getEndpoints(spec);
+  const schemas = getSchemas(spec);
+  const tags = getTags(spec);
+  const url = getServerUrl(spec);
+  const sv = spec.openapi || spec.swagger || "unknown";
+
+  const lines: string[] = [
+    `# ${spec.info.title}`,
+    "",
+    `Version: ${spec.info.version}`,
+    `OpenAPI Version: ${sv}`,
+    `Server: \`${url || "Not specified"}\``,
+    "",
+    spec.info.description || "",
+    "",
+    "## Summary",
+    `- Endpoints: ${eps.length}`,
+    `- Schemas: ${schemas.length}`,
+    `- Tags: ${tags.length}`,
+  ];
+
+  if (spec.info.contact) {
+    lines.push("", "## Contact");
+    for (const k of ["name", "email", "url"] as const) {
+      const val = spec.info.contact[k];
+      if (val)
+        lines.push(`- ${k.charAt(0).toUpperCase() + k.slice(1)}: ${val}`);
+    }
+  }
+
+  if (spec.info.license) {
+    lines.push("", "## License");
+    lines.push(`- Name: ${spec.info.license.name}`);
+    if (spec.info.license.url) lines.push(`- URL: ${spec.info.license.url}`);
+  }
+
+  return lines.join("\n");
+}

package/src/commands/paths.ts

@@ -0,0 +1,43 @@
+import { loadSpec } from "../core/loader.ts";
+import { getEndpoints } from "../core/queries.ts";
+
+export async function cmdPaths(
+  source: string,
+  tag?: string,
+  limit = 50,
+  offset = 0,
+): Promise<string> {
+  const spec = await loadSpec(source);
+  const all = getEndpoints(spec, tag);
+  const paginated = all.slice(offset, offset + limit);
+
+  if (!paginated.length) {
+    return all.length === 0
+      ? "No endpoints found."
+      : `No more endpoints (offset ${offset} of ${all.length}).`;
+  }
+
+  const hasMore = all.length > offset + paginated.length;
+  const lines: string[] = ["# Endpoints"];
+  if (tag) lines.push(`\nFiltered by tag: \`${tag}\``);
+  lines.push(`\n${all.length} total (showing ${paginated.length})`, "");
+
+  for (const ep of paginated) {
+    lines.push(
+      `### \`${ep.method.toUpperCase()}\` ${ep.path}${ep.deprecated ? " ~~(deprecated)~~" : ""}`,
+    );
+    if (ep.summary) lines.push(ep.summary);
+    if (ep.operationId) lines.push(`- Operation ID: \`${ep.operationId}\``);
+    if (ep.tags.length)
+      lines.push(`- Tags: ${ep.tags.map((t) => `\`${t}\``).join(", ")}`);
+    lines.push("");
+  }
+
+  if (hasMore) {
+    lines.push(
+      `> Showing ${paginated.length} of ${all.length}. Use --offset=${offset + paginated.length} to see more.`,
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/commands/schema.ts

@@ -0,0 +1,22 @@
+import { loadSpec } from "../core/loader.ts";
+import { getSchemas, getSchemaDetail } from "../core/queries.ts";
+import { fmtSchema } from "../formatters/schema.ts";
+
+export async function cmdSchema(
+  source: string,
+  schemaName: string,
+): Promise<string> {
+  const spec = await loadSpec(source);
+  const schema = getSchemaDetail(spec, schemaName);
+  if (!schema) {
+    const suggestions = getSchemas(spec)
+      .slice(0, 10)
+      .map((s) => s.name);
+    throw new Error(
+      `Schema '${schemaName}' not found.\n\nAvailable:\n${suggestions.map((s) => `  - ${s}`).join("\n")}`,
+    );
+  }
+  return [`# Schema: ${schemaName}`, "", "```", fmtSchema(schema), "```"].join(
+    "\n",
+  );
+}

package/src/commands/schemas.ts

@@ -0,0 +1,45 @@
+import { loadSpec } from "../core/loader.ts";
+import { getSchemas } from "../core/queries.ts";
+
+export async function cmdSchemas(
+  source: string,
+  limit = 50,
+  offset = 0,
+): Promise<string> {
+  const spec = await loadSpec(source);
+  const all = getSchemas(spec);
+  const paginated = all.slice(offset, offset + limit);
+
+  if (!paginated.length) {
+    return all.length === 0
+      ? "No schemas defined."
+      : `No more schemas (offset ${offset} of ${all.length}).`;
+  }
+
+  const hasMore = all.length > offset + paginated.length;
+  const lines: string[] = [
+    "# Component Schemas",
+    "",
+    `${all.length} total (showing ${paginated.length})`,
+    "",
+    "| Name | Type | Properties | Description |",
+    "|------|------|------------|-------------|",
+  ];
+
+  for (const s of paginated) {
+    lines.push(
+      `| \`${s.name}\` | ${s.type} | ${s.properties} | ${(s.description || "").slice(0, 80)} |`,
+    );
+  }
+
+  if (hasMore) {
+    lines.push(
+      `\n> Showing ${paginated.length} of ${all.length}. Use --offset=${offset + paginated.length} to see more.`,
+    );
+  }
+
+  lines.push(
+    "\nUse `openapi-explorer schema <source> <schema_name>` for details.",
+  );
+  return lines.join("\n");
+}

package/src/commands/search.ts

@@ -0,0 +1,49 @@
+import { loadSpec } from "../core/loader.ts";
+import { searchSpec } from "../core/queries.ts";
+
+export async function cmdSearch(
+  source: string,
+  query: string,
+): Promise<string> {
+  const spec = await loadSpec(source);
+  const results = searchSpec(spec, query);
+  if (!results.length) return `No results for '${query}'.`;
+
+  const lines: string[] = [
+    `# Search Results for '${query}'`,
+    "",
+    `Found ${results.length} matches`,
+    "",
+  ];
+
+  const eps = results.filter((r) => r.type === "endpoint");
+  const schemas = results.filter((r) => r.type === "schema");
+  const props = results.filter((r) => r.type === "property");
+
+  if (eps.length) {
+    lines.push(`## Endpoints (${eps.length})`);
+    for (const e of eps)
+      lines.push(
+        `- ${e.method?.toUpperCase()} \`${e.path}\` - ${e.summary || ""}`,
+      );
+    lines.push("");
+  }
+
+  if (schemas.length) {
+    lines.push(`## Schemas (${schemas.length})`);
+    for (const s of schemas)
+      lines.push(`- ${s.schemaName} - ${s.summary || ""}`);
+    lines.push("");
+  }
+
+  if (props.length) {
+    lines.push(`## Properties (${props.length})`);
+    for (const p of props)
+      lines.push(
+        `- \`${p.schemaName}.${p.propertyName}\` - ${p.summary || ""}`,
+      );
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/commands/tags.ts

@@ -0,0 +1,11 @@
+import { loadSpec } from "../core/loader.ts";
+import { getTags } from "../core/queries.ts";
+
+export async function cmdTags(source: string): Promise<string> {
+  const spec = await loadSpec(source);
+  const tags = getTags(spec);
+  if (!tags.length) return "No tags found.";
+  const lines = ["# Tags", "", "| Tag | Endpoints |", "|-----|-----------|"];
+  for (const t of tags) lines.push(`| \`${t.name}\` | ${t.count} |`);
+  return lines.join("\n");
+}

package/src/core/loader.ts

@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { OpenAPISpec } from "../types.ts";
+
+export async function loadSpec(source: string): Promise<OpenAPISpec> {
+  const isUrl = /^https?:\/\//i.test(source);
+  let raw: string;
+
+  if (isUrl) {
+    const res = await fetch(source, {
+      headers: { Accept: "application/json, text/plain" },
+      signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${source}`);
+    raw = await res.text();
+  } else {
+    raw = await readFile(resolve(source), "utf-8");
+  }
+
+  const data = JSON.parse(raw) as OpenAPISpec;
+  if (!data.openapi && !data.swagger)
+    throw new Error("Not a valid OpenAPI/Swagger spec.");
+  if (!data.info) throw new Error("Invalid spec: missing 'info' field.");
+  data.info.title = data.info.title || "Untitled API";
+  data.info.version = data.info.version || "0.0.0";
+  data.paths = data.paths || {};
+  return data;
+}
+
+export function getServerUrl(spec: OpenAPISpec): string {
+  if (spec.servers?.length) {
+    let url = spec.servers[0]!.url;
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+  }
+  if (spec.host)
+    return `${spec.schemes?.[0] || "https"}://${spec.host}${spec.basePath || ""}`;
+  return "";
+}