openapi-ai-generator 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+type Provider = 'azure' | 'openai' | 'anthropic';
+type JSDocMode = 'context' | 'exact';
+interface OpenAPIGenConfig {
+    provider: Provider;
+    output: {
+        specPath: string;
+        scalarDocs?: boolean;
+        scalarPath?: string;
+    };
+    openapi: {
+        title: string;
+        version: string;
+        description?: string;
+        servers?: Array<{
+            url: string;
+            description?: string;
+        }>;
+    };
+    jsdocMode?: JSDocMode;
+    cache?: boolean;
+    cacheDir?: string;
+    include?: string[];
+    exclude?: string[];
+}
+interface ResolvedConfig extends Required<OpenAPIGenConfig> {
+    output: Required<OpenAPIGenConfig['output']>;
+    openapi: Required<OpenAPIGenConfig['openapi']>;
+}
+declare function resolveConfig(config: OpenAPIGenConfig): ResolvedConfig;
+declare function loadConfig(configPath?: string): Promise<ResolvedConfig>;
+
+interface RouteInfo {
+    filePath: string;
+    relativePath: string;
+    urlPath: string;
+    sourceCode: string;
+    jsdocComments: string[];
+    hasExactJsdoc: boolean;
+    exactPathItem?: Record<string, unknown>;
+}
+declare function scanRoutes(include: string[], exclude: string[], cwd?: string): Promise<RouteInfo[]>;
+/**
+ * Convert a Next.js route file path to an OpenAPI URL path.
+ * e.g. src/app/api/users/[id]/route.ts -> /api/users/{id}
+ */
+declare function filePathToUrlPath(filePath: string): string;
+
+interface AnalyzeOptions {
+    provider: Provider;
+    jsdocMode: JSDocMode;
+    cache: boolean;
+    cacheDir: string;
+}
+interface AnalyzedRoute {
+    urlPath: string;
+    pathItem: Record<string, unknown>;
+    fromCache: boolean;
+    skippedLLM: boolean;
+}
+declare function analyzeRoutes(routes: RouteInfo[], options: AnalyzeOptions): Promise<AnalyzedRoute[]>;
+
+interface OpenAPISpec {
+    openapi: '3.1.0';
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, unknown>;
+}
+declare function assembleSpec(config: ResolvedConfig, routes: AnalyzedRoute[]): OpenAPISpec;
+declare function writeOutputFiles(config: ResolvedConfig, spec: OpenAPISpec, cwd?: string): void;
+
+interface GenerateOptions {
+    config?: string;
+    provider?: OpenAPIGenConfig['provider'];
+    cache?: boolean;
+    cwd?: string;
+}
+interface GenerateResult {
+    routesAnalyzed: number;
+    routesFromCache: number;
+    routesSkippedLLM: number;
+    specPath: string;
+}
+declare function generate(options?: GenerateOptions): Promise<GenerateResult>;
+
+export { type GenerateOptions, type GenerateResult, type JSDocMode, type OpenAPIGenConfig, type Provider, type ResolvedConfig, analyzeRoutes, assembleSpec, filePathToUrlPath, generate, loadConfig, resolveConfig, scanRoutes, writeOutputFiles };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+type Provider = 'azure' | 'openai' | 'anthropic';
+type JSDocMode = 'context' | 'exact';
+interface OpenAPIGenConfig {
+    provider: Provider;
+    output: {
+        specPath: string;
+        scalarDocs?: boolean;
+        scalarPath?: string;
+    };
+    openapi: {
+        title: string;
+        version: string;
+        description?: string;
+        servers?: Array<{
+            url: string;
+            description?: string;
+        }>;
+    };
+    jsdocMode?: JSDocMode;
+    cache?: boolean;
+    cacheDir?: string;
+    include?: string[];
+    exclude?: string[];
+}
+interface ResolvedConfig extends Required<OpenAPIGenConfig> {
+    output: Required<OpenAPIGenConfig['output']>;
+    openapi: Required<OpenAPIGenConfig['openapi']>;
+}
+declare function resolveConfig(config: OpenAPIGenConfig): ResolvedConfig;
+declare function loadConfig(configPath?: string): Promise<ResolvedConfig>;
+
+interface RouteInfo {
+    filePath: string;
+    relativePath: string;
+    urlPath: string;
+    sourceCode: string;
+    jsdocComments: string[];
+    hasExactJsdoc: boolean;
+    exactPathItem?: Record<string, unknown>;
+}
+declare function scanRoutes(include: string[], exclude: string[], cwd?: string): Promise<RouteInfo[]>;
+/**
+ * Convert a Next.js route file path to an OpenAPI URL path.
+ * e.g. src/app/api/users/[id]/route.ts -> /api/users/{id}
+ */
+declare function filePathToUrlPath(filePath: string): string;
+
+interface AnalyzeOptions {
+    provider: Provider;
+    jsdocMode: JSDocMode;
+    cache: boolean;
+    cacheDir: string;
+}
+interface AnalyzedRoute {
+    urlPath: string;
+    pathItem: Record<string, unknown>;
+    fromCache: boolean;
+    skippedLLM: boolean;
+}
+declare function analyzeRoutes(routes: RouteInfo[], options: AnalyzeOptions): Promise<AnalyzedRoute[]>;
+
+interface OpenAPISpec {
+    openapi: '3.1.0';
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, unknown>;
+}
+declare function assembleSpec(config: ResolvedConfig, routes: AnalyzedRoute[]): OpenAPISpec;
+declare function writeOutputFiles(config: ResolvedConfig, spec: OpenAPISpec, cwd?: string): void;
+
+interface GenerateOptions {
+    config?: string;
+    provider?: OpenAPIGenConfig['provider'];
+    cache?: boolean;
+    cwd?: string;
+}
+interface GenerateResult {
+    routesAnalyzed: number;
+    routesFromCache: number;
+    routesSkippedLLM: number;
+    specPath: string;
+}
+declare function generate(options?: GenerateOptions): Promise<GenerateResult>;
+
+export { type GenerateOptions, type GenerateResult, type JSDocMode, type OpenAPIGenConfig, type Provider, type ResolvedConfig, analyzeRoutes, assembleSpec, filePathToUrlPath, generate, loadConfig, resolveConfig, scanRoutes, writeOutputFiles };

package/dist/index.js

@@ -0,0 +1,476 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var url = require('url');
+var glob = require('glob');
+var ai = require('ai');
+var crypto = require('crypto');
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var defaults = {
+  jsdocMode: "context",
+  cache: true,
+  cacheDir: ".openapi-cache",
+  include: ["src/app/api/**/route.ts"],
+  exclude: []
+};
+function resolveConfig(config) {
+  return {
+    ...defaults,
+    ...config,
+    output: {
+      scalarDocs: false,
+      scalarPath: "src/app/api/docs/route.ts",
+      ...config.output
+    },
+    openapi: {
+      description: "",
+      servers: [],
+      ...config.openapi
+    }
+  };
+}
+async function loadConfig(configPath) {
+  const searchPaths = configPath ? [configPath] : [
+    "openapi-gen.config.ts",
+    "openapi-gen.config.js",
+    "openapi-gen.config.mjs",
+    "openapi-gen.config.cjs"
+  ];
+  for (const p of searchPaths) {
+    const abs = path.resolve(process.cwd(), p);
+    if (fs.existsSync(abs)) {
+      const mod = await importConfig(abs);
+      const config = mod.default ?? mod;
+      return resolveConfig(config);
+    }
+  }
+  throw new Error(
+    "No openapi-gen.config.ts found. Create one at your project root."
+  );
+}
+async function importConfig(filePath) {
+  if (filePath.endsWith(".ts")) {
+    return importTypeScriptConfig(filePath);
+  }
+  const url$1 = url.pathToFileURL(filePath).href;
+  return import(url$1);
+}
+async function importTypeScriptConfig(filePath) {
+  try {
+    const { register } = await import('module');
+    const url$1 = url.pathToFileURL(filePath).href;
+    return await import(url$1);
+  } catch {
+    try {
+      __require("ts-node/register");
+      return __require(filePath);
+    } catch {
+      throw new Error(
+        `Cannot load TypeScript config file: ${filePath}. Install tsx or ts-node, or use a .js config file.`
+      );
+    }
+  }
+}
+async function scanRoutes(include, exclude, cwd = process.cwd()) {
+  const files = await glob.glob(include, {
+    cwd,
+    ignore: exclude,
+    absolute: true
+  });
+  return files.map((filePath) => parseRoute(filePath, cwd));
+}
+function parseRoute(filePath, cwd) {
+  const relativePath = path.relative(cwd, filePath);
+  const sourceCode = fs.readFileSync(filePath, "utf8");
+  const urlPath = filePathToUrlPath(relativePath);
+  const { jsdocComments, hasExactJsdoc, exactPathItem } = extractJsdoc(sourceCode);
+  return {
+    filePath,
+    relativePath,
+    urlPath,
+    sourceCode,
+    jsdocComments,
+    hasExactJsdoc,
+    exactPathItem
+  };
+}
+function filePathToUrlPath(filePath) {
+  let path = filePath.replace(/\\/g, "/");
+  path = path.replace(/^(src\/)?app\//, "");
+  path = path.replace(/\/route\.(ts|tsx|js|jsx)$/, "");
+  path = path.replace(/\[([^\]]+)\]/g, (_, param) => {
+    if (param.startsWith("...")) {
+      return `{${param.slice(3)}}`;
+    }
+    return `{${param}}`;
+  });
+  if (!path.startsWith("/")) {
+    path = "/" + path;
+  }
+  return path;
+}
+function extractJsdoc(sourceCode) {
+  const jsdocRegex = /\/\*\*([\s\S]*?)\*\//g;
+  const jsdocComments = [];
+  let hasExactJsdoc = false;
+  let exactPathItem;
+  let match;
+  while ((match = jsdocRegex.exec(sourceCode)) !== null) {
+    const comment = match[0];
+    jsdocComments.push(comment);
+    if (/@openapi-exact/.test(comment)) {
+      hasExactJsdoc = true;
+      const openapiMatch = comment.match(/@openapi\s+([\s\S]*?)(?=\s*\*\/|\s*\*\s*@)/);
+      if (openapiMatch) {
+        try {
+          const jsonStr = openapiMatch[1].split("\n").map((line) => line.replace(/^\s*\*\s?/, "")).join("\n").trim();
+          exactPathItem = JSON.parse(jsonStr);
+        } catch {
+          hasExactJsdoc = false;
+        }
+      }
+    }
+  }
+  return { jsdocComments, hasExactJsdoc, exactPathItem };
+}
+function computeHash(content, provider, modelId) {
+  return crypto.createHash("sha256").update(content).update(provider).update(modelId).digest("hex");
+}
+var RouteCache = class {
+  cacheDir;
+  constructor(cacheDir) {
+    this.cacheDir = cacheDir;
+  }
+  ensureDir() {
+    if (!fs.existsSync(this.cacheDir)) {
+      fs.mkdirSync(this.cacheDir, { recursive: true });
+    }
+  }
+  get(hash) {
+    const filePath = path.join(this.cacheDir, `${hash}.json`);
+    if (!fs.existsSync(filePath)) return null;
+    try {
+      const entry = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      return entry.pathItem;
+    } catch {
+      return null;
+    }
+  }
+  set(hash, pathItem) {
+    this.ensureDir();
+    const entry = {
+      hash,
+      pathItem,
+      cachedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const filePath = path.join(this.cacheDir, `${hash}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), "utf8");
+  }
+};
+
+// src/providers/index.ts
+function createModel(provider) {
+  switch (provider) {
+    case "azure":
+      return createAzureModel();
+    case "openai":
+      return createOpenAIModel();
+    case "anthropic":
+      return createAnthropicModel();
+    default: {
+      const _exhaustive = provider;
+      throw new Error(`Unknown provider: ${_exhaustive}`);
+    }
+  }
+}
+function createAzureModel() {
+  const endpoint = requireEnv("AZURE_OPENAI_ENDPOINT");
+  const apiKey = requireEnv("AZURE_OPENAI_API_KEY");
+  const deployment = requireEnv("AZURE_OPENAI_DEPLOYMENT");
+  const { createAzure } = __require("@ai-sdk/azure");
+  const azure = createAzure({ endpoint, apiKey });
+  return azure(deployment);
+}
+function createOpenAIModel() {
+  const apiKey = requireEnv("OPENAI_API_KEY");
+  const model = process.env.OPENAI_MODEL ?? "gpt-4o";
+  const { createOpenAI } = __require("@ai-sdk/openai");
+  const openai = createOpenAI({ apiKey });
+  return openai(model);
+}
+function createAnthropicModel() {
+  const apiKey = requireEnv("ANTHROPIC_API_KEY");
+  const model = process.env.ANTHROPIC_MODEL ?? "claude-sonnet-4-6";
+  const { createAnthropic } = __require("@ai-sdk/anthropic");
+  const anthropic = createAnthropic({ apiKey });
+  return anthropic(model);
+}
+function requireEnv(name) {
+  const val = process.env[name];
+  if (!val) {
+    throw new Error(`Required environment variable ${name} is not set.`);
+  }
+  return val;
+}
+function getModelId(provider) {
+  switch (provider) {
+    case "azure":
+      return process.env.AZURE_OPENAI_DEPLOYMENT ?? "unknown";
+    case "openai":
+      return process.env.OPENAI_MODEL ?? "gpt-4o";
+    case "anthropic":
+      return process.env.ANTHROPIC_MODEL ?? "claude-sonnet-4-6";
+  }
+}
+
+// src/analyzer.ts
+async function analyzeRoutes(routes, options) {
+  const modelId = getModelId(options.provider);
+  const cache = options.cache ? new RouteCache(options.cacheDir) : null;
+  let model = null;
+  const getModel = () => {
+    if (!model) model = createModel(options.provider);
+    return model;
+  };
+  const results = [];
+  for (const route of routes) {
+    const result = await analyzeRoute(route, options, modelId, cache, getModel);
+    results.push(result);
+  }
+  return results;
+}
+async function analyzeRoute(route, options, modelId, cache, getModel) {
+  if (route.hasExactJsdoc && route.exactPathItem) {
+    return {
+      urlPath: route.urlPath,
+      pathItem: route.exactPathItem,
+      fromCache: false,
+      skippedLLM: true
+    };
+  }
+  if (options.jsdocMode === "exact") {
+    if (route.hasExactJsdoc && route.exactPathItem) {
+      return {
+        urlPath: route.urlPath,
+        pathItem: route.exactPathItem,
+        fromCache: false,
+        skippedLLM: true
+      };
+    }
+  }
+  const hash = computeHash(route.sourceCode, options.provider, modelId);
+  if (cache) {
+    const cached = cache.get(hash);
+    if (cached) {
+      return {
+        urlPath: route.urlPath,
+        pathItem: cached,
+        fromCache: true,
+        skippedLLM: true
+      };
+    }
+  }
+  const pathItem = await callLLM(route, options.jsdocMode, getModel());
+  if (cache) {
+    cache.set(hash, pathItem);
+  }
+  return {
+    urlPath: route.urlPath,
+    pathItem,
+    fromCache: false,
+    skippedLLM: false
+  };
+}
+function buildPrompt(route, jsdocMode) {
+  const jsDocSection = route.jsdocComments.length > 0 ? `JSDoc COMMENTS (use as ${jsdocMode === "context" ? "additional context" : "primary source"}):
+${route.jsdocComments.join("\n\n")}` : "No JSDoc comments found.";
+  return `You are an OpenAPI 3.1 specification generator. Analyze the following Next.js API route and extract a complete OpenAPI PathItem object.
+
+FILE PATH: ${route.relativePath}
+INFERRED URL PATH: ${route.urlPath}
+
+SOURCE CODE:
+\`\`\`typescript
+${route.sourceCode}
+\`\`\`
+
+${jsDocSection}
+
+Extract the following for EACH exported HTTP method handler (GET, POST, PUT, PATCH, DELETE):
+- operationId (camelCase, unique)
+- summary (short description)
+- description (detailed description)
+- path parameters (from URL segments like [id])
+- query parameters (from NextRequest.nextUrl.searchParams usage)
+- request body schema (from request.json() usage and TypeScript types)
+- response schemas (per status code, from NextResponse.json() calls and return types)
+- tags (infer from path segments)
+- security requirements (if auth middleware or token checks are present)
+
+Return ONLY a valid JSON object matching the OpenAPI 3.1 PathItem schema. No explanation, no markdown, no code blocks. Just the raw JSON object.`;
+}
+async function callLLM(route, jsdocMode, model) {
+  const prompt = buildPrompt(route, jsdocMode);
+  const { text } = await ai.generateText({
+    model,
+    prompt,
+    temperature: 0
+  });
+  return parsePathItem(text, route.urlPath);
+}
+function parsePathItem(text, urlPath) {
+  let json = text.trim();
+  if (json.startsWith("```")) {
+    json = json.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+  }
+  try {
+    const parsed = JSON.parse(json);
+    if (typeof parsed !== "object" || Array.isArray(parsed) || parsed === null) {
+      throw new Error("Response is not a JSON object");
+    }
+    return parsed;
+  } catch (err) {
+    console.warn(
+      `Warning: Failed to parse LLM response for ${urlPath}. Using empty PathItem.`,
+      err
+    );
+    return {};
+  }
+}
+function assembleSpec(config, routes) {
+  const paths = {};
+  for (const route of routes) {
+    if (Object.keys(route.pathItem).length > 0) {
+      paths[route.urlPath] = route.pathItem;
+    }
+  }
+  const spec = {
+    openapi: "3.1.0",
+    info: {
+      title: config.openapi.title,
+      version: config.openapi.version,
+      ...config.openapi.description ? { description: config.openapi.description } : {}
+    },
+    paths
+  };
+  if (config.openapi.servers && config.openapi.servers.length > 0) {
+    spec.servers = config.openapi.servers;
+  }
+  return spec;
+}
+function writeOutputFiles(config, spec, cwd = process.cwd()) {
+  writeSpecFiles(config, spec, cwd);
+  if (config.output.scalarDocs) {
+    writeScalarRoute(config, cwd);
+  }
+}
+function writeSpecFiles(config, spec, cwd) {
+  const specRoutePath = path.resolve(cwd, config.output.specPath);
+  const specDir = path.dirname(specRoutePath);
+  ensureDir(specDir);
+  const specJsonPath = path.join(specDir, "spec.json");
+  fs.writeFileSync(specJsonPath, JSON.stringify(spec, null, 2), "utf8");
+  const routeContent = `import spec from './spec.json';
+
+export const dynamic = 'force-static';
+
+export function GET() {
+  return Response.json(spec);
+}
+`;
+  fs.writeFileSync(specRoutePath, routeContent, "utf8");
+}
+function writeScalarRoute(config, cwd) {
+  const scalarRoutePath = path.resolve(cwd, config.output.scalarPath);
+  ensureDir(path.dirname(scalarRoutePath));
+  const specUrl = filePathToApiUrl(config.output.specPath);
+  const routeContent = `export const dynamic = 'force-static';
+
+export function GET() {
+  return new Response(
+    \`<!doctype html>
+<html>
+  <head>
+    <title>API Docs</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      data-url="${specUrl}"
+    ></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>\`,
+    { headers: { 'Content-Type': 'text/html' } }
+  );
+}
+`;
+  fs.writeFileSync(scalarRoutePath, routeContent, "utf8");
+}
+function filePathToApiUrl(filePath) {
+  let path = filePath.replace(/\\/g, "/");
+  path = path.replace(/^(src\/)?app\//, "");
+  path = path.replace(/\/route\.(ts|tsx|js|jsx)$/, "");
+  if (!path.startsWith("/")) path = "/" + path;
+  return path;
+}
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// src/index.ts
+async function generate(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = await loadConfig(options.config);
+  if (options.provider) config.provider = options.provider;
+  if (options.cache === false) config.cache = false;
+  console.log(`[openapi-ai-generator] Scanning routes...`);
+  const routes = await scanRoutes(config.include, config.exclude, cwd);
+  console.log(`[openapi-ai-generator] Found ${routes.length} route(s)`);
+  console.log(`[openapi-ai-generator] Analyzing routes with provider: ${config.provider}`);
+  const analyzed = await analyzeRoutes(routes, {
+    provider: config.provider,
+    jsdocMode: config.jsdocMode,
+    cache: config.cache,
+    cacheDir: config.cacheDir
+  });
+  const fromCache = analyzed.filter((r) => r.fromCache).length;
+  const skippedLLM = analyzed.filter((r) => r.skippedLLM).length;
+  console.log(
+    `[openapi-ai-generator] ${analyzed.length} routes analyzed (${fromCache} from cache, ${skippedLLM - fromCache} exact JSDoc)`
+  );
+  const spec = assembleSpec(config, analyzed);
+  writeOutputFiles(config, spec, cwd);
+  console.log(`[openapi-ai-generator] Spec written to ${config.output.specPath}`);
+  if (config.output.scalarDocs) {
+    console.log(`[openapi-ai-generator] Scalar docs written to ${config.output.scalarPath}`);
+  }
+  return {
+    routesAnalyzed: analyzed.length,
+    routesFromCache: fromCache,
+    routesSkippedLLM: skippedLLM,
+    specPath: config.output.specPath
+  };
+}
+
+exports.analyzeRoutes = analyzeRoutes;
+exports.assembleSpec = assembleSpec;
+exports.filePathToUrlPath = filePathToUrlPath;
+exports.generate = generate;
+exports.loadConfig = loadConfig;
+exports.resolveConfig = resolveConfig;
+exports.scanRoutes = scanRoutes;
+exports.writeOutputFiles = writeOutputFiles;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map