swgto-ts 2.0.1 → 3.0.1

package/README.md

@@ -81,6 +81,7 @@ export interface SwaggerTsConfig {
   fileNaming?: 'module' | 'path'
   flattenQueryParam?: boolean
   mergeParams?: boolean
+  apiDocs?: ApiDocsConfig
 }
 ```
 
@@ -101,6 +102,7 @@ export interface SwaggerTsConfig {
 | `cleanOutput`        | `boolean`                           | `false`      | 生成前是否清空输出目录                                                                                                                 |
 | `flattenQueryParam`  | `boolean`                           | `false`      | 当 query 参数只有一个且为 `$ref` 引用类型时，直接用引用类型代替 `{ query: RefType }`                                                   |
 | `mergeParams`        | `boolean`                           | `false`      | 合并参数层级：`true` 时展平 `path/query/body` 嵌套，直接使用 `params: { field1, field2 }` 代替 `params: { path: {...}, query: {...} }` |
+| `apiDocs`            | `ApiDocsConfig`                     | 见说明       | 自动生成 API 文档（HTML/Markdown），详细配置见 [API 文档生成](#api-文档生成)                                                         |
 
 ### 函数名生成规则
 
@@ -145,3 +147,50 @@ getUser({ path: { id: '1' }, query: { name: 'foo' } })
 // mergeParams: true，参数展平
 getUser({ id: '1', name: 'foo' })
 ```
+
+### API 文档生成
+
+配置 `apiDocs` 可在生成代码的同时，自动输出一份人类可读的 API 文档：
+
+```ts
+export default {
+  // ... 其他配置
+  apiDocs: {
+    enable: true,
+    format: 'html',           // 'html' 或 'markdown'
+    output: 'api-docs.html',  // 输出文件名
+    title: '我的 API 文档',    // 文档标题，默认取 OpenAPI info.title
+    companyName: 'XX 公司',   // 封面公司名称（仅 HTML）
+    template: './my-template.html', // 自定义 HTML 模板路径（仅 HTML）
+    theme: './my-theme.css',  // 自定义样式文件路径（仅 HTML）
+  },
+}
+```
+
+| 配置项        | 类型                        | 默认值                  | 说明                                                           |
+| ------------- | --------------------------- | ----------------------- | -------------------------------------------------------------- |
+| `enable`      | `boolean`                   | `false`                 | 是否开启文档生成                                               |
+| `format`      | `'html' \| 'markdown'`      | `'html'`                | 输出格式：HTML 适合浏览器打印为 PDF，Markdown 适合仓库内查看   |
+| `output`      | `string`                    | `'api-docs.html'`       | 输出文件名，相对 `outputDir`                                   |
+| `title`       | `string`                    | OpenAPI `info.title`    | 文档标题                                                       |
+| `companyName` | `string`                    | 无                      | 封面上的公司名称（仅 HTML）                                    |
+| `template`    | `string`                    | 内置模板                | 自定义 HTML 模板路径（仅 HTML）。优先级：`template` 配置 > 项目根目录 `.swagger.docs.html` > 内置默认模板 |
+| `theme`       | `string`                    | 无                      | 自定义 CSS 文件路径，覆盖文档样式（仅 HTML）                   |
+
+#### HTML 文档
+
+输出为带书本风格的 HTML 页面，包含：
+- **封面页**：A4 整页，显示公司名称（如配置）、API 名称和版本号
+- **目录**：方法 + 路径 | 点线 | 摘要，点击跳转到对应接口
+- **接口卡片**：包含路径参数、查询参数、请求体、响应体的字段表格（名称 / 类型 / 必填 / 描述）
+
+可通过项目根目录的 `.swagger.docs.html` 文件自定义文档样式。如果设置了 `apiDocs.template`，则优先使用该路径的模板文件。
+
+#### Markdown 文档
+
+输出为 `.md` 文件，包含：
+- 封面区域：公司名称（如配置）、API 名称和版本号
+- 目录（Table of Contents）：所有接口的锚点链接列表
+- 每个接口的详细说明：HTTP 方法 + 路径、描述、参数表格和响应表格
+
+适合直接在代码仓库中查看或用于 GitBook、VuePress 等文档工具。```

package/dist/chunk-HBBM5HFP.js

@@ -0,0 +1,64 @@
+// src/generators/schemaToTs.ts
+function formatPropertyName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function refToTypeName(ref) {
+  const parts = ref.split("/");
+  return parts[parts.length - 1] || "unknown";
+}
+function schemaToTs(schema) {
+  if (!schema) {
+    return "unknown";
+  }
+  if (schema.$ref) {
+    return refToTypeName(schema.$ref);
+  }
+  if (schema.enum?.length) {
+    return schema.enum.map((item) => JSON.stringify(item)).join(" | ");
+  }
+  if (schema.anyOf?.length) {
+    return schema.anyOf.map((item) => schemaToTs(item)).join(" | ");
+  }
+  if (schema.oneOf?.length) {
+    return schema.oneOf.map((item) => schemaToTs(item)).join(" | ");
+  }
+  if (schema.allOf?.length) {
+    return schema.allOf.map((item) => schemaToTs(item)).join(" & ");
+  }
+  if (schema.type === "array") {
+    return `${schemaToTs(schema.items)}[]`;
+  }
+  if (schema.type === "object" || schema.properties) {
+    const requiredSet = new Set(schema.required ?? []);
+    const properties = Object.entries(schema.properties ?? {}).map(([key, value]) => {
+      const optional = requiredSet.has(key) ? "" : "?";
+      return `${formatPropertyName(key)}${optional}: ${schemaToTs(value)};`;
+    });
+    if (!properties.length && schema.additionalProperties) {
+      const valueType = schema.additionalProperties === true ? "unknown" : schemaToTs(schema.additionalProperties);
+      return `{ [key: string]: ${valueType} }`;
+    }
+    return `{ ${properties.join(" ")} }`;
+  }
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "string":
+      return "string";
+    case "null":
+      return "null";
+    default:
+      return "unknown";
+  }
+}
+function toTypePropertyName(name) {
+  return formatPropertyName(name);
+}
+
+export {
+  schemaToTs,
+  toTypePropertyName
+};

package/dist/{chunk-ZURWUVPF.js → chunk-OMXGXES2.js}

@@ -1,5 +1,12 @@
+import {
+  schemaToTs,
+  toTypePropertyName
+} from "./chunk-HBBM5HFP.js";
+
 // src/generate.ts
 import path4 from "path";
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile2 } from "fs/promises";
 
 // src/config/loadConfig.ts
 import { existsSync } from "fs";
@@ -33,6 +40,8 @@ async function loadConfig(cwd) {
   const rawConfig = loaded?.default ?? loaded;
   assertConfig(rawConfig);
   const docUrls = Array.isArray(rawConfig.docUrls) ? rawConfig.docUrls : [rawConfig.docUrls];
+  const apiDocsFormat = rawConfig.apiDocs?.format ?? "html";
+  const defaultOutput = apiDocsFormat === "markdown" ? "api-docs.md" : "api-docs.html";
   const config = {
     ...rawConfig,
     docUrls,
@@ -42,7 +51,16 @@ async function loadConfig(cwd) {
     cleanOutput: rawConfig.cleanOutput ?? false,
     fileNaming: rawConfig.fileNaming ?? "path",
     flattenQueryParam: rawConfig.flattenQueryParam ?? false,
-    mergeParams: rawConfig.mergeParams ?? false
+    mergeParams: rawConfig.mergeParams ?? false,
+    apiDocs: {
+      enable: rawConfig.apiDocs?.enable ?? false,
+      output: rawConfig.apiDocs?.output ?? defaultOutput,
+      format: apiDocsFormat,
+      title: rawConfig.apiDocs?.title,
+      companyName: rawConfig.apiDocs?.companyName,
+      template: rawConfig.apiDocs?.template,
+      theme: rawConfig.apiDocs?.theme
+    }
   };
   return { configPath, config };
 }
@@ -142,66 +160,6 @@ function groupByController(operations) {
   }, {});
 }
 
-// src/generators/schemaToTs.ts
-function formatPropertyName(name) {
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
-}
-function refToTypeName(ref) {
-  const parts = ref.split("/");
-  return parts[parts.length - 1] || "unknown";
-}
-function schemaToTs(schema) {
-  if (!schema) {
-    return "unknown";
-  }
-  if (schema.$ref) {
-    return refToTypeName(schema.$ref);
-  }
-  if (schema.enum?.length) {
-    return schema.enum.map((item) => JSON.stringify(item)).join(" | ");
-  }
-  if (schema.anyOf?.length) {
-    return schema.anyOf.map((item) => schemaToTs(item)).join(" | ");
-  }
-  if (schema.oneOf?.length) {
-    return schema.oneOf.map((item) => schemaToTs(item)).join(" | ");
-  }
-  if (schema.allOf?.length) {
-    return schema.allOf.map((item) => schemaToTs(item)).join(" & ");
-  }
-  if (schema.type === "array") {
-    return `${schemaToTs(schema.items)}[]`;
-  }
-  if (schema.type === "object" || schema.properties) {
-    const requiredSet = new Set(schema.required ?? []);
-    const properties = Object.entries(schema.properties ?? {}).map(([key, value]) => {
-      const optional = requiredSet.has(key) ? "" : "?";
-      return `${formatPropertyName(key)}${optional}: ${schemaToTs(value)};`;
-    });
-    if (!properties.length && schema.additionalProperties) {
-      const valueType = schema.additionalProperties === true ? "unknown" : schemaToTs(schema.additionalProperties);
-      return `{ [key: string]: ${valueType} }`;
-    }
-    return `{ ${properties.join(" ")} }`;
-  }
-  switch (schema.type) {
-    case "integer":
-    case "number":
-      return "number";
-    case "boolean":
-      return "boolean";
-    case "string":
-      return "string";
-    case "null":
-      return "null";
-    default:
-      return "unknown";
-  }
-}
-function toTypePropertyName(name) {
-  return formatPropertyName(name);
-}
-
 // src/utils/naming.ts
 function toPascalCase(value) {
   return value.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((segment) => segment[0].toUpperCase() + segment.slice(1)).join("");
@@ -503,15 +461,13 @@ ${queryLine}${bodyLine}    ...config,
 }`;
 }
 function generateTsRequestFile(operation, httpClientPath, typeImportPath, mergeParams = false) {
-  const importTypes = [
-    ...operation.requestImportTypes,
-    operation.responseTypeName,
-    "RequestConfig"
-  ].filter((value, index, array) => Boolean(value) && array.indexOf(value) === index);
+  const importTypes = [...operation.requestImportTypes, operation.responseTypeName, "RequestConfig"].filter(
+    (value, index, array) => Boolean(value) && array.indexOf(value) === index
+  );
   const importLine = importTypes.length ? `import type { ${importTypes.join(", ")} } from ${JSON.stringify(typeImportPath)};
 ` : "";
   const buildUrlHelper = operation.pathParams.length ? `
-function buildUrl(path?: Record<string, unknown>): string {
+function buildUrl(path?: Record<string, any>): string {
   return ${JSON.stringify(operation.requestPath)}.replace(/\\{([^}]+)\\}/g, (_, key) => String(path?.[key] ?? ''));
 }
 ` : "";
@@ -789,14 +745,52 @@ async function generateFromConfig(cwd = process.cwd()) {
     path4.relative(cwd, typesFile),
     path4.relative(cwd, indexFile)
   );
+  if (config.apiDocs.enable) {
+    let content;
+    const docFile = path4.join(cwd, config.outputDir, config.apiDocs.output);
+    if (config.apiDocs.format === "markdown") {
+      const { generateApiDocsMd } = await import("./genApiDocsMd-WVDJY3ST.js");
+      content = generateApiDocsMd(documentMap, operations, config);
+    } else {
+      const { generateApiDocsHtml, DEFAULT_TEMPLATE } = await import("./genApiDocsHtml-V7PDR4PW.js");
+      const templateFile = path4.join(cwd, ".swagger.docs.html");
+      if (!existsSync2(templateFile)) {
+        await writeTextFile(templateFile, DEFAULT_TEMPLATE);
+        console.log(`Created template: .swagger.docs.html`);
+      }
+      const templatePaths = [];
+      if (config.apiDocs.template) {
+        templatePaths.push(path4.resolve(cwd, config.apiDocs.template));
+      }
+      templatePaths.push(templateFile);
+      let templateHtml;
+      for (const tp of templatePaths) {
+        if (existsSync2(tp)) {
+          templateHtml = await readFile2(tp, "utf-8");
+          break;
+        }
+      }
+      let themeCss;
+      if (config.apiDocs.theme) {
+        const themePath = path4.resolve(cwd, config.apiDocs.theme);
+        if (existsSync2(themePath)) {
+          themeCss = await readFile2(themePath, "utf-8");
+        }
+      }
+      content = generateApiDocsHtml(documentMap, operations, config, templateHtml, themeCss);
+    }
+    await writeTextFile(docFile, content);
+    files.push(path4.relative(cwd, docFile));
+  }
   await saveSnapshot(snapshotPath, operations);
+  const htmlGenerated = config.apiDocs.enable ? 1 : 0;
   return {
     configPath,
     files,
     operationCount: operations.length,
     moduleCount: Object.keys(grouped).length,
-    apiFileCount: files.length - 2,
-    // exclude types + index
+    apiFileCount: files.length - 2 - htmlGenerated,
+    // exclude types + index + optional html
     newOperations,
     removedOperations
   };

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
   generateFromConfig
-} from "./chunk-ZURWUVPF.js";
+} from "./chunk-OMXGXES2.js";
+import "./chunk-HBBM5HFP.js";
 
 // src/cli.ts
 async function main() {
@@ -12,6 +13,10 @@ async function main() {
     console.log(`swgto loaded config: ${result.configPath}`);
     console.log(`Generated ${result.apiFileCount} api file(s), ${result.operationCount} operation(s) in ${result.moduleCount} module(s).`);
     console.log(`Wrote ${result.files.length} file(s) total (including types, index).`);
+    const docFile = result.files.find((f) => f.endsWith(".html") || f.endsWith(".md"));
+    if (docFile) {
+      console.log(`Generated API docs: ${docFile}`);
+    }
     console.log(`Done in ${elapsedMs}ms.`);
     if (result.newOperations.length > 0) {
       console.log(`

package/dist/genApiDocsHtml-V7PDR4PW.js

@@ -0,0 +1,382 @@
+import {
+  schemaToTs
+} from "./chunk-HBBM5HFP.js";
+
+// src/generators/genApiDocsHtml.ts
+function getMethodColor(method) {
+  const colors = {
+    get: "#1677ff",
+    post: "#52c41a",
+    put: "#fa8c16",
+    patch: "#722ed1",
+    delete: "#ff4d4f",
+    head: "#8c8c8c",
+    options: "#8c8c8c"
+  };
+  return colors[method.toLowerCase()] ?? "#8c8c8c";
+}
+function paramTypeDisplay(schema) {
+  if (!schema) return "unknown";
+  if (schema.type && !schema.$ref && !schema.enum && !schema.properties) {
+    return schema.type;
+  }
+  return schemaToTs(schema);
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function resolveSchemaRef(schema, docUrl, documentMap) {
+  if (!schema?.$ref) return schema;
+  const name = schema.$ref.split("/").pop();
+  const doc = documentMap.get(docUrl);
+  const schemas = doc?.components?.schemas;
+  return schemas?.[name];
+}
+function refName(schema) {
+  if (schema?.$ref) return schema.$ref.split("/").pop();
+  if (schema?.type === "array" && schema.items?.$ref) return schema.items.$ref.split("/").pop();
+  return void 0;
+}
+function renderSchemaFieldsTable(schema, docUrl, documentMap, visitedRefs = /* @__PURE__ */ new Set()) {
+  const resolved = resolveSchemaRef(schema, docUrl, documentMap);
+  if (!resolved) {
+    return `<div class="schema-block">${escapeHtml(schemaToTs(schema))}</div>`;
+  }
+  if (resolved.properties && Object.keys(resolved.properties).length > 0) {
+    const requiredSet = new Set(resolved.required ?? []);
+    const doc = documentMap.get(docUrl);
+    const allSchemas = doc?.components?.schemas;
+    let html = '<table><thead><tr><th class="col-name">\u540D\u79F0</th><th class="col-type">\u7C7B\u578B</th><th class="col-req">\u5FC5\u586B</th><th class="col-desc">\u63CF\u8FF0</th></tr></thead><tbody>';
+    for (const [key, prop] of Object.entries(resolved.properties)) {
+      const subRef = refName(prop);
+      const subSchema = subRef && !visitedRefs.has(subRef) ? allSchemas?.[subRef] : void 0;
+      if (subSchema?.properties) {
+        visitedRefs.add(subRef);
+        const typeText = schemaToTs(prop);
+        html += '<tr class="ref-row"><td colspan="4">';
+        html += `<details class="ref-details"><summary class="ref-summary">`;
+        html += `<span class="ref-toggle">\u25B6</span>`;
+        html += `<span class="code ref-fname">${escapeHtml(key)}</span>`;
+        html += `<span class="code ref-ftype">${escapeHtml(typeText)}</span>`;
+        html += `<span class="${requiredSet.has(key) ? "required ref-freq" : "ref-freq"}">${requiredSet.has(key) ? "\u662F" : "\u5426"}</span>`;
+        html += `<span class="ref-fdesc">${prop.description ? escapeHtml(prop.description) : "-"}</span>`;
+        html += `</summary><div class="ref-body">`;
+        html += renderSchemaFieldsTable(subSchema, docUrl, documentMap, visitedRefs);
+        html += `</div></details></td></tr>`;
+      } else {
+        const typeText = schemaToTs(prop);
+        html += "<tr>";
+        html += `<td class="code">${escapeHtml(key)}</td>`;
+        html += `<td class="code">${escapeHtml(typeText)}</td>`;
+        html += `<td class="${requiredSet.has(key) ? "required" : ""}">${requiredSet.has(key) ? "\u662F" : "\u5426"}</td>`;
+        html += `<td>${prop.description ? escapeHtml(prop.description) : "-"}</td>`;
+        html += "</tr>";
+      }
+    }
+    html += "</tbody></table>";
+    return html;
+  }
+  return `<div class="schema-block">${escapeHtml(schemaToTs(schema))}</div>`;
+}
+var PLACEHOLDER = {
+  TITLE: "{{TITLE}}",
+  COVER_COMPANY: "{{COVER_COMPANY}}",
+  COVER_TITLE: "{{COVER_TITLE}}",
+  COVER_VERSION: "{{COVER_VERSION}}",
+  COVER_DATE: "{{COVER_DATE}}",
+  STAT_ENDPOINT_COUNT: "{{STAT_ENDPOINT_COUNT}}",
+  STAT_MODULE_COUNT: "{{STAT_MODULE_COUNT}}",
+  STYLES: "{{STYLES}}",
+  TOC: "{{TOC}}",
+  ENDPOINT_CARDS: "{{ENDPOINT_CARDS}}"
+};
+var DEFAULT_STYLES = `
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', 'Helvetica Neue', Arial, sans-serif;
+  color: #1f1f1f;
+  background: #f5f5f5;
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+.cover {
+  display: flex; flex-direction: column; justify-content: center; align-items: center;
+  min-height: 100vh; min-height: 297mm;
+  background: linear-gradient(135deg, #1677ff 0%, #0958d9 100%);
+  color: #fff; text-align: center; padding: 60px 40px;
+  page-break-after: always;
+}
+.cover-company { font-size: 14px; letter-spacing: 4px; opacity: 0.6; margin-bottom: 32px; text-transform: uppercase; }
+.cover h1 { font-size: 40px; font-weight: 700; margin-bottom: 8px; letter-spacing: 2px; }
+.cover .version { font-size: 18px; opacity: 0.85; margin-bottom: 48px; }
+.cover .meta { font-size: 13px; opacity: 0.55; }
+.cover .stats { margin-top: 16px; display: flex; justify-content: center; gap: 40px; }
+.cover .stat-item { text-align: center; }
+.cover .stat-num { font-size: 28px; font-weight: 600; }
+.cover .stat-label { font-size: 12px; opacity: 0.65; }
+
+.container { max-width: 960px; margin: 0 auto; padding: 0 24px 48px; }
+
+.toc { margin-bottom: 40px; }
+.toc h2 {
+  font-size: 22px; font-weight: 700; color: #1f1f1f; margin-bottom: 16px;
+  padding-bottom: 10px; border-bottom: 2px solid #1f1f1f; letter-spacing: 2px;
+}
+.toc-group { margin-bottom: 24px; }
+.toc-group:last-child { margin-bottom: 0; }
+.toc-module {
+  font-size: 14px; font-weight: 600; color: #1677ff; margin-bottom: 8px;
+  padding-left: 2px;
+}
+.toc-entry {
+  display: flex; align-items: baseline; text-decoration: none;
+  padding: 3px 4px; color: #434343; page-break-inside: avoid;
+  overflow: hidden;
+}
+.toc-entry:hover { background: #f5f5f5; border-radius: 3px; }
+.toc-badge {
+  display: inline-block; padding: 1px 5px; border-radius: 3px; font-size: 10px;
+  font-weight: 700; color: #fff; font-family: 'SFMono-Regular', Consolas, monospace;
+  min-width: 40px; text-align: center; flex-shrink: 0; margin-right: 8px;
+}
+.toc-path {
+  font-family: 'SFMono-Regular', Consolas, monospace; font-size: 13px;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex-shrink: 1; min-width: 40px;
+}
+.toc-leader {
+  flex: 1; min-width: 12px; margin: 0 6px;
+  border-bottom: 1px dotted #d9d9d9; height: 0; align-self: center;
+}
+.toc-summary {
+  font-size: 12px; color: #8c8c8c; white-space: nowrap;
+  flex-shrink: 0; text-align: right; max-width: 45%;
+  overflow: hidden; text-overflow: ellipsis;
+}
+
+.card {
+  background: #fff; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,.08);
+  margin-bottom: 20px; overflow: hidden; page-break-inside: avoid;
+}
+.card-header {
+  display: flex; align-items: center; gap: 12px; padding: 14px 20px;
+  border-bottom: 1px solid #f0f0f0;
+}
+.method-badge {
+  display: inline-block; padding: 3px 10px; border-radius: 4px; font-size: 13px;
+  font-weight: 700; color: #fff; font-family: 'SFMono-Regular', Consolas, monospace; min-width: 56px; text-align: center;
+}
+.card-path { font-family: 'SFMono-Regular', Consolas, monospace; font-size: 14px; font-weight: 500; color: #1f1f1f; word-break: break-all; }
+.card-summary { flex: 1; text-align: right; font-size: 13px; color: #8c8c8c; }
+.card-body { padding: 16px 20px; }
+.card-section { margin-bottom: 14px; }
+.card-section:last-child { margin-bottom: 0; }
+.card-section-title { font-size: 13px; font-weight: 600; color: #434343; margin-bottom: 6px; }
+.card-section-desc { font-size: 13px; color: #595959; margin-bottom: 8px; line-height: 1.5; }
+.card-desc-empty { font-style: italic; color: #bfbfbf; font-size: 13px; }
+
+table { width: 100%; border-collapse: collapse; font-size: 13px; table-layout: fixed; }
+thead th {
+  background: #fafafa; text-align: left; padding: 6px 10px; font-weight: 600;
+  color: #595959; border-bottom: 1px solid #e8e8e8; font-size: 12px;
+}
+tbody td { padding: 6px 10px; border-bottom: 1px solid #f5f5f5; color: #595959; vertical-align: top; word-break: break-word; }
+tbody tr:hover { background: #fafafa; }
+td.code { font-family: 'SFMono-Regular', Consolas, monospace; font-size: 12px; }
+td.required { color: #ff4d4f; font-weight: 600; }
+.col-name { width: 28%; }
+.col-type { width: 18%; }
+.col-loc  { width: 10%; }
+.col-req  { width: 7%; }
+.col-desc { width: auto; }
+
+.schema-block {
+  background: #f6f8fa; border-radius: 4px; padding: 10px 14px;
+  font-family: 'SFMono-Regular', Consolas, monospace; font-size: 12px; line-height: 1.7;
+  color: #1f1f1f; overflow-x: auto; white-space: pre-wrap; word-break: break-word;
+}
+
+.ref-row td { padding: 0 !important; border-bottom: none !important; }
+.ref-row:hover { background: transparent; }
+.ref-summary {
+  display: flex; align-items: center; gap: 8px; cursor: pointer; user-select: none;
+  padding: 6px 10px; list-style: none; font-size: 12px;
+}
+.ref-summary::-webkit-details-marker { display: none; }
+.ref-summary::marker { display: none; }
+.ref-toggle { font-size: 10px; color: #8c8c8c; width: 14px; flex-shrink: 0; text-align: center; transition: transform .15s; }
+details[open] .ref-toggle { transform: rotate(90deg); }
+.ref-fname { width: 28%; font-family: 'SFMono-Regular', Consolas, monospace; font-size: 12px; flex-shrink: 0; }
+.ref-ftype { width: 18%; font-family: 'SFMono-Regular', Consolas, monospace; font-size: 12px; color: #595959; flex-shrink: 0; }
+.ref-freq { width: 7%; font-size: 12px; flex-shrink: 0; }
+.ref-fdesc { flex: 1; font-size: 12px; color: #595959; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ref-body { padding: 2px 0 8px 0; }
+.ref-body table { font-size: 12px; }
+.ref-body th { font-size: 11px; padding: 4px 8px; }
+.ref-body td { padding: 4px 8px; }
+
+@media print {
+  body { background: #fff; }
+  .cover { border-radius: 0; min-height: 297mm; page-break-after: always; }
+  .card { box-shadow: none; border: 1px solid #e8e8e8; page-break-inside: avoid; }
+  @page { margin: 0; }
+}
+`;
+var DEFAULT_TEMPLATE = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${PLACEHOLDER.TITLE}</title>
+<style>${PLACEHOLDER.STYLES}</style>
+</head>
+<body>
+<div class="container">
+<div class="cover">
+  <div class="cover-company">${PLACEHOLDER.COVER_COMPANY}</div>
+  <h1>${PLACEHOLDER.COVER_TITLE}</h1>
+  <div class="version">${PLACEHOLDER.COVER_VERSION}</div>
+  <div class="meta">${PLACEHOLDER.COVER_DATE}</div>
+  <div class="stats">
+    <div class="stat-item"><div class="stat-num">${PLACEHOLDER.STAT_ENDPOINT_COUNT}</div><div class="stat-label">\u63A5\u53E3</div></div>
+    <div class="stat-item"><div class="stat-num">${PLACEHOLDER.STAT_MODULE_COUNT}</div><div class="stat-label">\u6A21\u5757</div></div>
+  </div>
+</div>
+${PLACEHOLDER.TOC}
+${PLACEHOLDER.ENDPOINT_CARDS}
+</div>
+</body>
+</html>`;
+function renderTocHtml(operations) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const op of operations) {
+    const list = grouped.get(op.moduleName);
+    if (list) {
+      list.push(op);
+    } else {
+      grouped.set(op.moduleName, [op]);
+    }
+  }
+  const groups = Array.from(grouped.entries());
+  let html = '<div class="toc"><h2>\u76EE\u5F55</h2>';
+  for (const [moduleName, ops] of groups) {
+    html += `<div class="toc-group"><div class="toc-module">${escapeHtml(moduleName)}</div>`;
+    for (const op of ops) {
+      const anchor = `#${op.functionName}`;
+      const color = getMethodColor(op.method);
+      html += `<a class="toc-entry" href="${anchor}">`;
+      html += `<span class="toc-badge" style="background:${color}">${op.method.toUpperCase()}</span>`;
+      html += `<span class="toc-path">${escapeHtml(op.path)}</span>`;
+      html += '<span class="toc-leader"></span>';
+      if (op.summary) {
+        html += `<span class="toc-summary">${escapeHtml(op.summary)}</span>`;
+      }
+      html += "</a>";
+    }
+    html += "</div>";
+  }
+  html += "</div>";
+  return html;
+}
+function renderParamsTableHtml(params) {
+  if (!params.length) {
+    return '<span class="card-desc-empty">\u65E0</span>';
+  }
+  let html = '<table><thead><tr><th class="col-name">\u540D\u79F0</th><th class="col-type">\u7C7B\u578B</th><th class="col-req">\u5FC5\u586B</th><th class="col-desc">\u63CF\u8FF0</th></tr></thead><tbody>';
+  for (const p of params) {
+    const typeText = paramTypeDisplay(p.schema);
+    html += "<tr>";
+    html += `<td class="code">${escapeHtml(p.name)}</td>`;
+    html += `<td class="code">${escapeHtml(typeText)}</td>`;
+    html += `<td class="${p.required ? "required" : ""}">${p.required ? "\u662F" : "\u5426"}</td>`;
+    html += `<td>${p.description ? escapeHtml(p.description) : "-"}</td>`;
+    html += "</tr>";
+  }
+  html += "</tbody></table>";
+  return html;
+}
+function renderEndpointCardHtml(op, documentMap) {
+  const color = getMethodColor(op.method);
+  const anchor = op.functionName;
+  let html = `<div class="card" id="${anchor}">`;
+  html += '<div class="card-header">';
+  html += `<span class="method-badge" style="background:${color}">${op.method.toUpperCase()}</span>`;
+  html += `<span class="card-path">${escapeHtml(op.path)}</span>`;
+  if (op.summary) {
+    html += `<span class="card-summary">${escapeHtml(op.summary)}</span>`;
+  }
+  html += "</div>";
+  html += '<div class="card-body">';
+  if (op.description) {
+    html += '<div class="card-section">';
+    html += `<div class="card-section-desc">${escapeHtml(op.description)}</div>`;
+    html += "</div>";
+  }
+  if (op.pathParams.length) {
+    html += '<div class="card-section">';
+    html += '<div class="card-section-title">\u8DEF\u5F84\u53C2\u6570</div>';
+    html += renderParamsTableHtml(op.pathParams);
+    html += "</div>";
+  }
+  if (op.queryParams.length) {
+    html += '<div class="card-section">';
+    html += '<div class="card-section-title">\u67E5\u8BE2\u53C2\u6570</div>';
+    html += renderParamsTableHtml(op.queryParams);
+    html += "</div>";
+  }
+  if (op.requestBodySchema) {
+    html += '<div class="card-section">';
+    html += '<div class="card-section-title">\u8BF7\u6C42\u4F53</div>';
+    html += renderSchemaFieldsTable(op.requestBodySchema, op.docUrl, documentMap);
+    html += "</div>";
+  }
+  if (op.responseSchema) {
+    html += '<div class="card-section">';
+    html += '<div class="card-section-title">\u54CD\u5E94</div>';
+    html += renderSchemaFieldsTable(op.responseSchema, op.docUrl, documentMap);
+    html += "</div>";
+  }
+  html += "</div></div>";
+  return html;
+}
+function buildTemplateContext(documentMap, operations, config, themeCss) {
+  const firstDoc = documentMap.values().next().value;
+  const title = config.apiDocs.title || firstDoc?.info?.title || "API Documentation";
+  const version = firstDoc?.info?.version ? `v${firstDoc.info.version}` : "";
+  const now = /* @__PURE__ */ new Date();
+  const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+  const modules = new Set(operations.map((op) => op.moduleName));
+  const moduleCount = modules.size;
+  const fullStyles = themeCss ? DEFAULT_STYLES + "\n" + themeCss : DEFAULT_STYLES;
+  return {
+    title: escapeHtml(title),
+    coverCompany: config.apiDocs.companyName ? escapeHtml(config.apiDocs.companyName) : "",
+    coverTitle: escapeHtml(title),
+    coverVersion: escapeHtml(version),
+    coverDate: dateStr,
+    statEndpointCount: String(operations.length),
+    statModuleCount: String(moduleCount),
+    styles: fullStyles,
+    toc: renderTocHtml(operations),
+    endpointCards: operations.map((op) => renderEndpointCardHtml(op, documentMap)).join("\n")
+  };
+}
+function applyTemplate(templateHtml, ctx) {
+  return templateHtml.replace(PLACEHOLDER.TITLE, ctx.title).replace(PLACEHOLDER.COVER_COMPANY, ctx.coverCompany).replace(PLACEHOLDER.COVER_TITLE, ctx.coverTitle).replace(PLACEHOLDER.COVER_VERSION, ctx.coverVersion).replace(PLACEHOLDER.COVER_DATE, ctx.coverDate).replace(PLACEHOLDER.STAT_ENDPOINT_COUNT, ctx.statEndpointCount).replace(PLACEHOLDER.STAT_MODULE_COUNT, ctx.statModuleCount).replace(PLACEHOLDER.STYLES, ctx.styles).replace(PLACEHOLDER.TOC, ctx.toc).replace(PLACEHOLDER.ENDPOINT_CARDS, ctx.endpointCards);
+}
+function generateApiDocsHtml(documentMap, operations, config, templateHtml, themeCss) {
+  const ctx = buildTemplateContext(documentMap, operations, config, themeCss);
+  const template = templateHtml ?? DEFAULT_TEMPLATE;
+  return applyTemplate(template, ctx);
+}
+export {
+  DEFAULT_STYLES,
+  DEFAULT_TEMPLATE,
+  PLACEHOLDER,
+  applyTemplate,
+  buildTemplateContext,
+  generateApiDocsHtml,
+  renderEndpointCardHtml,
+  renderParamsTableHtml,
+  renderTocHtml
+};

package/dist/genApiDocsMd-WVDJY3ST.js

@@ -0,0 +1,153 @@
+import {
+  schemaToTs
+} from "./chunk-HBBM5HFP.js";
+
+// src/generators/genApiDocsMd.ts
+function paramTypeDisplay(schema) {
+  if (!schema) return "unknown";
+  if (schema.type && !schema.$ref && !schema.enum && !schema.properties) {
+    return schema.type;
+  }
+  return schemaToTs(schema);
+}
+function escapeMd(str) {
+  return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function resolveSchemaRef(schema, docUrl, documentMap) {
+  if (!schema?.$ref) return schema;
+  const name = schema.$ref.split("/").pop();
+  const doc = documentMap.get(docUrl);
+  const schemas = doc?.components?.schemas;
+  return schemas?.[name];
+}
+function refName(schema) {
+  if (schema?.$ref) return schema.$ref.split("/").pop();
+  if (schema?.type === "array" && schema.items?.$ref) return schema.items.$ref.split("/").pop();
+  return void 0;
+}
+function renderMdTable(rows, headers) {
+  const cols = headers.length;
+  const lines = [];
+  lines.push(`| ${headers.join(" | ")} |`);
+  lines.push(`| ${headers.map(() => "---").join(" | ")} |`);
+  for (const row of rows) {
+    lines.push(`| ${row.join(" | ")} |`);
+  }
+  return lines.join("\n");
+}
+function renderParamsMdTable(params) {
+  if (!params.length) return "\u65E0";
+  const rows = params.map((p) => [
+    `\`${escapeMd(p.name)}\``,
+    `\`${escapeMd(paramTypeDisplay(p.schema))}\``,
+    p.required ? "**\u662F**" : "\u5426",
+    escapeMd(p.description ?? "-")
+  ]);
+  return renderMdTable(rows, ["\u540D\u79F0", "\u7C7B\u578B", "\u5FC5\u586B", "\u63CF\u8FF0"]);
+}
+function renderSchemaFieldsMd(schema, docUrl, documentMap, visitedRefs = /* @__PURE__ */ new Set(), depth = 0) {
+  const resolved = resolveSchemaRef(schema, docUrl, documentMap);
+  if (!resolved) return `\`${escapeMd(schemaToTs(schema))}\``;
+  if (resolved.properties && Object.keys(resolved.properties).length > 0) {
+    const requiredSet = new Set(resolved.required ?? []);
+    const doc = documentMap.get(docUrl);
+    const allSchemas = doc?.components?.schemas;
+    const rows = [];
+    const subBlocks = [];
+    for (const [key, prop] of Object.entries(resolved.properties)) {
+      const typeText = schemaToTs(prop);
+      const subRef = refName(prop);
+      const subSchema = subRef && !visitedRefs.has(subRef) ? allSchemas?.[subRef] : void 0;
+      rows.push([
+        `\`${escapeMd(key)}\``,
+        `\`${escapeMd(typeText)}\``,
+        requiredSet.has(key) ? "**\u662F**" : "\u5426",
+        escapeMd(prop.description ?? "-")
+      ]);
+      if (subSchema?.properties) {
+        visitedRefs.add(subRef);
+        subBlocks.push(`
+<details>
+<summary>${escapeMd(key)}: ${escapeMd(subRef)}</summary>
+
+${renderSchemaFieldsMd(subSchema, docUrl, documentMap, visitedRefs, depth + 1)}
+</details>
+`);
+      }
+    }
+    let md = renderMdTable(rows, ["\u540D\u79F0", "\u7C7B\u578B", "\u5FC5\u586B", "\u63CF\u8FF0"]);
+    if (subBlocks.length > 0) {
+      md += "\n" + subBlocks.join("\n");
+    }
+    return md;
+  }
+  return `\`${escapeMd(schemaToTs(schema))}\``;
+}
+function generateApiDocsMd(documentMap, operations, config) {
+  const firstDoc = documentMap.values().next().value;
+  const title = config.apiDocs.title || firstDoc?.info?.title || "API Documentation";
+  const version = firstDoc?.info?.version ? `v${firstDoc.info.version}` : "";
+  const now = /* @__PURE__ */ new Date();
+  const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+  const modules = new Set(operations.map((op) => op.moduleName));
+  const moduleCount = modules.size;
+  const lines = [];
+  if (config.apiDocs.companyName) {
+    lines.push(`> ${config.apiDocs.companyName}`);
+    lines.push("");
+  }
+  lines.push(`# ${title}`);
+  if (version) lines.push(`**\u7248\u672C**: ${version}`);
+  lines.push(`**\u751F\u6210\u65E5\u671F**: ${dateStr}`);
+  lines.push(`**\u63A5\u53E3\u603B\u6570**: ${operations.length} | **\u6A21\u5757\u6570**: ${moduleCount}`);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("## \u76EE\u5F55");
+  lines.push("");
+  for (const op of operations) {
+    const anchor = op.summary ? `${op.method.toUpperCase()} ${op.path} \u2014 ${op.summary}` : `${op.method.toUpperCase()} ${op.path}`;
+    lines.push(`- [${escapeMd(anchor)}](#${op.functionName})`);
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  for (const op of operations) {
+    lines.push(`## ${op.summary || op.functionName}`);
+    lines.push("");
+    lines.push(`\`${op.method.toUpperCase()}\` \`${op.path}\``);
+    lines.push("");
+    if (op.description) {
+      lines.push(op.description);
+      lines.push("");
+    }
+    if (op.pathParams.length) {
+      lines.push("### \u8DEF\u5F84\u53C2\u6570");
+      lines.push("");
+      lines.push(renderParamsMdTable(op.pathParams));
+      lines.push("");
+    }
+    if (op.queryParams.length) {
+      lines.push("### \u67E5\u8BE2\u53C2\u6570");
+      lines.push("");
+      lines.push(renderParamsMdTable(op.queryParams));
+      lines.push("");
+    }
+    if (op.requestBodySchema) {
+      lines.push("### \u8BF7\u6C42\u4F53");
+      lines.push("");
+      lines.push(renderSchemaFieldsMd(op.requestBodySchema, op.docUrl, documentMap));
+      lines.push("");
+    }
+    if (op.responseSchema) {
+      lines.push("### \u54CD\u5E94");
+      lines.push("");
+      lines.push(renderSchemaFieldsMd(op.responseSchema, op.docUrl, documentMap));
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+export {
+  generateApiDocsMd
+};

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 type OutputType = 'ts' | 'js';
 type RequestConfig = Record<string, unknown>;
+type ApiDocsFormat = 'html' | 'markdown';
+interface ApiDocsConfig {
+    enable?: boolean;
+    output?: string;
+    format?: ApiDocsFormat;
+    title?: string;
+    companyName?: string;
+    template?: string;
+    theme?: string;
+}
 interface SwaggerTsConfig {
     docUrls: string | string[];
     httpClientPath: string;
@@ -14,6 +24,7 @@ interface SwaggerTsConfig {
     fileNaming?: 'module' | 'path';
     flattenQueryParam?: boolean;
     mergeParams?: boolean;
+    apiDocs?: ApiDocsConfig;
 }
 
 interface SnapshotEntry {
@@ -37,4 +48,4 @@ interface GenerateResult {
 }
 declare function generateFromConfig(cwd?: string): Promise<GenerateResult>;
 
-export { type GenerateResult, type RequestConfig, type SwaggerTsConfig, generateFromConfig };
+export { type ApiDocsConfig, type GenerateResult, type RequestConfig, type SwaggerTsConfig, generateFromConfig };

package/dist/index.js

@@ -1,6 +1,7 @@
 import {
   generateFromConfig
-} from "./chunk-ZURWUVPF.js";
+} from "./chunk-OMXGXES2.js";
+import "./chunk-HBBM5HFP.js";
 export {
   generateFromConfig
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swgto-ts",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "description": "Generate API request files from OpenAPI 3.x documents.",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,9 @@
     "generator",
     "cli"
   ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "engines": {
     "node": ">=18"
   },