apidoc-to-openapi 0.1.1

package/README.md

@@ -0,0 +1,76 @@
+# apidoc-to-openapi
+
+A CLI utility that scans source files with `apidoc` and converts parsed apidoc metadata into an OpenAPI 3.0 document (`json` or `yaml`).
+
+## Install
+
+```bash
+npm install
+```
+
+You can run it directly with:
+
+```bash
+npx apidoc-to-openapi --src ./src --output ./openapi.yaml
+```
+
+Or after a global/local link:
+
+```bash
+apidoc-to-openapi --src ./src --output ./openapi.yaml
+```
+
+## Usage
+
+```bash
+apidoc-to-openapi --src <dir> [options]
+```
+
+### Options
+
+- `-s, --src <dir>`: Source directory for apidoc scanning (required).
+- `-o, --output <file>`: Output file path. When omitted, writes to stdout.
+- `-f, --format <json|yaml>`: Output format. Auto-detected from output extension when omitted.
+- `--title <text>`: Override `info.title`.
+- `--api-version <text>`: Override `info.version`.
+- `--description <text>`: Override `info.description`.
+- `--server <url>`: Add server URL (repeatable).
+- `--include <list>`: `apidoc` include filters, comma-separated.
+- `--exclude <list>`: `apidoc` exclude filters, comma-separated.
+- `--silent`: Silence apidoc log output.
+- `--no-pretty`: Minified JSON output.
+- `-h, --help`: Show help.
+
+## Examples
+
+Generate YAML file:
+
+```bash
+apidoc-to-openapi --src ./src --output ./openapi.yaml
+```
+
+Generate JSON to stdout:
+
+```bash
+apidoc-to-openapi --src ./src --format json > openapi.json
+```
+
+Override OpenAPI info:
+
+```bash
+apidoc-to-openapi \
+  --src ./src \
+  --output ./openapi.yaml \
+  --title "My Service API" \
+  --api-version "2.1.0" \
+  --server "https://api.example.com"
+```
+
+## Notes
+
+- This converter targets common apidoc tags (`@api`, `@apiParam`, `@apiSuccess`, `@apiError`, `@apiHeader`).
+- The generated schema is best-effort for nested field names and array notation (for example `items[].id`).
+- Array-like type hints such as `Array`, `List`, `ArrayList`, `List<String>`, `Array<Object>` are recognized, and child fields like `data.id` are mapped to array item properties.
+- Description prefixes like `[direct|直销,distribution|分销] 销售方式` are parsed into OpenAPI `enum` (using the value before `|`) and optional `x-enumDescriptions`.
+- `apidoc` project metadata fields (`baseurl`, `baseUrl`, `url`) are used as a base path prefix for every OpenAPI path (for example `/dapi/v2/prodev` + `/task_service/sync_task_to_feishu_bitable`).
+- If `apidoc` parsing fails, the CLI exits with a non-zero status.

package/bin/apidoc-to-openapi.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+const exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "apidoc-to-openapi",
+  "version": "0.1.1",
+  "description": "CLI to convert apidoc comments into OpenAPI JSON/YAML.",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "apidoc-to-openapi": "./bin/apidoc-to-openapi.js"
+  },
+  "keywords": [
+    "apidoc",
+    "openapi",
+    "swagger",
+    "cli",
+    "api-documentation"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "node --check src/cli.js && node --check src/converter.js && node --check src/options.js",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "apidoc": "^1.2.0",
+    "yaml": "^2.5.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,115 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { createDoc } from "apidoc";
+
+import { apidocDataToOpenApi, serializeOpenApi } from "./converter.js";
+import { parseCliArgs, printHelp } from "./options.js";
+
+function parsePossiblyJson(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return value;
+  }
+
+  if (
+    !(trimmed.startsWith("{") || trimmed.startsWith("["))
+  ) {
+    return value;
+  }
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+
+function buildApidocConfig(options) {
+  const config = {
+    src: path.resolve(process.cwd(), options.src),
+    dryRun: true,
+    silent: options.silent,
+  };
+
+  if (options.includeFilters.length > 0) {
+    config.includeFilters = options.includeFilters;
+  }
+
+  if (options.excludeFilters.length > 0) {
+    config.excludeFilters = options.excludeFilters;
+  }
+
+  return config;
+}
+
+async function writeOutput(outputPath, content) {
+  const absoluteOutputPath = path.resolve(process.cwd(), outputPath);
+  const outputDir = path.dirname(absoluteOutputPath);
+  await fs.mkdir(outputDir, { recursive: true });
+  await fs.writeFile(absoluteOutputPath, content, "utf8");
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  let options;
+  try {
+    options = parseCliArgs(argv);
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n\n`);
+    printHelp();
+    return 1;
+  }
+
+  if (options.help) {
+    printHelp();
+    return 0;
+  }
+
+  if (!options.src) {
+    process.stderr.write("Error: --src is required.\n\n");
+    printHelp();
+    return 1;
+  }
+
+  try {
+    const apidocConfig = buildApidocConfig(options);
+    const doc = createDoc(apidocConfig);
+
+    if (doc === false || typeof doc !== "object") {
+      process.stderr.write("Error: apidoc parsing failed.\n");
+      return 2;
+    }
+
+    const openApi = apidocDataToOpenApi({
+      docData: parsePossiblyJson(doc.data),
+      project: parsePossiblyJson(doc.project),
+      title: options.title,
+      apiVersion: options.apiVersion,
+      description: options.description,
+      servers: options.servers,
+    });
+
+    const content = serializeOpenApi(openApi, options.format, options.pretty);
+
+    if (options.output) {
+      await writeOutput(options.output, content);
+      process.stdout.write(
+        `OpenAPI document written to ${path.resolve(process.cwd(), options.output)}\n`,
+      );
+      return 0;
+    }
+
+    process.stdout.write(content);
+    if (!content.endsWith("\n")) {
+      process.stdout.write("\n");
+    }
+    return 0;
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    return 2;
+  }
+}