ARTICLE · 1112947
前端使用豆包构建API文档自动生成器
前端使用豆包构建API文档自动生成器
豆包AI API文档生成
目录
• 1. API文档生成概述 • 2. 代码解析与AST提取 • 3. TypeScript类型提取 • 4. 豆包AI文档生成引擎 • 5. OpenAPI/Swagger文档生成 • 6. Markdown文档生成与美化 • 7. 文档版本管理 • 8. 交互式API文档页面 • 9. 与Git工作流集成 • 10. 总结
前端使用豆包构建API文档自动生成器
1. API文档生成概述
API文档是前后端协作的桥梁，但维护文档往往是开发者的痛点。利用豆包AI可以自动解析代码中的类型定义、函数签名和注释，生成结构化的API文档，包括OpenAPI/Swagger格式和Markdown文档。
2. 代码解析与AST提取
// src/services/codeParser.tsimport * as ts from'typescript';exportinterfaceParsedFunction {name: string;parameters: ParsedParam[];returnType: string;jsdoc?: string;decorators: string[];isAsync: boolean;lineNumber: number;}exportinterfaceParsedParam {name: string;type: string;optional: boolean;defaultValue?: string;description?: string;}exportclassCodeParser {parseFile(sourceCode: string, fileName: string): ParsedFunction[] {const sourceFile = ts.createSourceFile( fileName, sourceCode, ts.ScriptTarget.Latest,true, ts.ScriptKind.TSX );constfunctions: ParsedFunction[] = [];functionvisit(node: ts.Node) {// 解析函数声明if (ts.isFunctionDeclaration(node) && node.name) { functions.push(parseFunction(node, sourceCode)); }// 解析箭头函数变量if (ts.isVariableStatement(node)) {for (const declaration of node.declarationList.declarations) {if (ts.isArrowFunction(declaration.initializer!) || ts.isFunctionExpression(declaration.initializer!)) { functions.push(parseArrowFunction(declaration, sourceCode)); } } }// 解析类方法if (ts.isMethodDeclaration(node) && node.name) { functions.push(parseMethod(node, sourceCode)); } ts.forEachChild(node, visit); }visit(sourceFile);return functions; }}functionparseFunction(node: ts.FunctionDeclaration, source: string): ParsedFunction {const jsdoc = ts.getJSDocCommentsAndTags(node);return {name: node.name!.getText(),parameters: node.parameters.map(p =>parseParam(p)),returnType: node.type?.getText() || 'void',jsdoc: jsdoc.length > 0 ? jsdoc.map(j => j.getText()).join('\n') : undefined,decorators: [],isAsync: !!node.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword),lineNumber: ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).line + 1, };}functionparseParam(param: ts.ParameterDeclaration): ParsedParam {return {name: param.name.getText(),type: param.type?.getText() || 'any',optional: !!param.questionToken,defaultValue: param.initializer?.getText(), };}3. TypeScript类型提取
// 从TypeScript代码中提取类型定义exportfunctionextractTypeDefinitions(sourceCode: string): TypeDefinition[] {const sourceFile = ts.createSourceFile('temp.ts', sourceCode, ts.ScriptTarget.Latest, true);consttypes: TypeDefinition[] = [];functionvisit(node: ts.Node) {if (ts.isInterfaceDeclaration(node)) { types.push({name: node.name.text,kind: 'interface',members: node.members.map(m => ({name: m.name?.getText() || '',type: (m as ts.PropertySignature).type?.getText() || 'any',optional: !!(m as ts.PropertySignature).questionToken,jsdoc: ts.getJSDocCommentsAndTags(m).map(j => j.getText()).join('\n'), })), }); }if (ts.isTypeAliasDeclaration(node)) { types.push({name: node.name.text,kind: 'type',typeText: node.type.getText(), }); } ts.forEachChild(node, visit); }visit(sourceFile);return types;}4. 豆包AI文档生成引擎
// src/services/docGenerator.tsexportclassDocGenerator {privateapiKey: string;constructor(apiKey: string) {this.apiKey = apiKey; }asyncgenerateAPIDoc(parsedFunctions: ParsedFunction[],typeDefinitions: TypeDefinition[],moduleName: string ): Promise<APIDocumentation> {const context = {module: moduleName,functions: parsedFunctions.map(f => ({name: f.name,params: f.parameters.map(p =>`${p.name}: ${p.type}${p.optional ? '?' : ''}`),returns: f.returnType,jsdoc: f.jsdoc || '', })),types: typeDefinitions, };const prompt = `作为技术文档撰写专家，为以下前端API生成详细文档：模块：${moduleName}函数列表：${JSON.stringify(context.functions, null, 2)}类型定义：${JSON.stringify(context.types, null, 2)}要求：1. 为每个函数编写完整说明，包括： - 功能描述（一句话概括） - 参数表格（名称、类型、必填、说明） - 返回值说明 - 使用示例（TypeScript代码） - 错误处理说明2. 为每个类型编写字段说明3. 添加模块级使用指南返回JSON格式的文档结构。`;const response = awaitthis.callAPI(prompt);const match = response.match(/\{[\s\S]*\}/);return match ? JSON.parse(match[0]) : null; }// 根据TypeScript接口生成Mock数据示例asyncgenerateMockExamples(typeCode: string ): Promise<string> {const prompt = `根据以下TypeScript类型定义，生成JSON格式的示例数据：类型定义：\`\`\`typescript${typeCode}\`\`\`要求：生成真实、有意义的中文示例数据。只返回JSON。`;returnthis.callAPI(prompt); }privateasynccallAPI(prompt: string): Promise<string> {const response = awaitfetch('/api/doubao/chat', {method: 'POST',headers: {'Content-Type': 'application/json',Authorization: `Bearer ${this.apiKey}`, },body: JSON.stringify({model: 'doubao-pro-32k',messages: [{ role: 'system', content: '你是技术文档专家。' }, { role: 'user', content: prompt }],temperature: 0.3,max_tokens: 4096, }), });const data = await response.json();return data.choices[0].message.content; }}5. OpenAPI/Swagger文档生成
// 生成OpenAPI 3.0规范文档exportasyncfunctiongenerateOpenAPI(parsedFunctions: ParsedFunction[],apiInfo: { title: string; version: string; baseUrl: string },apiKey: string): Promise<string> {const prompt = `根据以下API函数信息，生成OpenAPI 3.0规范的JSON文档：API信息：${JSON.stringify(apiInfo)}函数列表：${JSON.stringify(parsedFunctions.map(f => ({ name: f.name, params: f.parameters, returns: f.returnType, jsdoc: f.jsdoc})))}生成完整的OpenAPI 3.0 JSON，包含paths、components/schemas等。只返回JSON。`;const response = awaitfetch('/api/doubao/chat', {method: 'POST',headers: {'Content-Type': 'application/json',Authorization: `Bearer ${apiKey}`, },body: JSON.stringify({model: 'doubao-pro-32k',messages: [{ role: 'user', content: prompt }],temperature: 0.1,max_tokens: 8192, }), });const data = await response.json();return data.choices[0].message.content;}// 渲染Swagger UIexportfunctionrenderSwaggerUI(spec: object, containerId: string) { (windowasany).SwaggerUIBundle({ spec,dom_id: `#${containerId}`,presets: [(windowasany).SwaggerUIBundle.presets.apis],layout: 'BaseLayout', });}6. Markdown文档生成与美化
// 生成美化的Markdown文档exportfunctiongenerateMarkdownDoc(doc: APIDocumentation, moduleName: string): string {let md = `# ${moduleName} API 文档\n\n> 🤖 由豆包AI自动生成 | 生成时间：${newDate().toLocaleString()}\n\n`;// 目录 md += `## 目录\n\n`; md += `- [概述](#概述)\n`; md += `- [类型定义](#类型定义)\n`; md += `- [API列表](#api列表)\n`;// 概述 md += `\n## 概述\n\n${doc.overview || moduleName + ' 模块提供了以下API方法。'}\n`;// 安装与引入 md += `\n### 引入方式\n\n\`\`\`typescript\nimport { ${doc.functions?.map(f => f.name).join(', ')} } from '${moduleName}';\n\`\`\`\n`;// API列表 md += `\n## API列表\n\n`;for (const func of doc.functions || []) { md += `### ${func.name}\n\n${func.description}\n\n`; md += `**参数**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n`;for (const param of func.params || []) { md += `| ${param.name} | \`${param.type}\` | ${param.required ? '是' : '否'} | ${param.description || '-'} |\n`; } md += `\n**返回值**: \`${func.returns || 'void'}\`\n\n`;if (func.example) { md += `**使用示例**\n\n\`\`\`typescript\n${func.example}\n\`\`\`\n\n`; } }return md;}7. 文档版本管理
// 文档版本管理interfaceDocVersion {version: string;content: string;timestamp: number;author: string;changes: string;}classDocVersionManager {privateversions: DocVersion[] = [];private storageKey = 'api_doc_versions';addVersion(version: string, content: string, author: string, changes: string): void {this.versions.push({ version, content, timestamp: Date.now(), author, changes });this.save(); }getLatest(): DocVersion | null {returnthis.versions[this.versions.length - 1] || null; }getHistory(): DocVersion[] {return [...this.versions].reverse(); }// 生成变更日志asyncgenerateChangelog(apiKey: string): Promise<string> {const changes = this.versions.map(v =>`- v${v.version}: ${v.changes}`).join('\n');const prompt = `整理以下版本变更记录，生成CHANGELOG.md：\n${changes}`;const response = awaitfetch('/api/doubao/chat', {method: 'POST',headers: {'Content-Type': 'application/json',Authorization: `Bearer ${apiKey}`, },body: JSON.stringify({model: 'doubao-pro-32k',messages: [{ role: 'user', content: prompt }],temperature: 0.2, }), });const data = await response.json();return data.choices[0].message.content; }privatesave(): void {localStorage.setItem(this.storageKey, JSON.stringify(this.versions)); }}8. 交互式API文档页面
// src/components/APIDocViewer.tsximportReact, { useState } from'react';exportconstAPIDocViewer: React.FC<{ doc: APIDocumentation }> = ({ doc }) => {const [activeFunc, setActiveFunc] = useState('');const [testResult, setTestResult] = useState('');consthandleTest = async (funcName: string, params: any) => {setTestResult('请求中...');try {const response = awaitfetch(`/api/test/${funcName}`, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify(params), });const data = await response.json();setTestResult(JSON.stringify(data, null, 2)); } catch (error: any) {setTestResult(`错误: ${error.message}`); } };return (<divclassName="api-doc-viewer"><asideclassName="doc-sidebar"><h3>📚 API 目录</h3><nav> {doc.functions?.map(func => (<akey={func.name}className={activeFunc === func.name ? 'active' : ''}onClick={() => setActiveFunc(func.name)} href={`#${func.name}`} > {func.name}</a> ))}</nav></aside><mainclassName="doc-content"><h2>{doc.title}</h2><p>{doc.overview}</p> {doc.functions?.map(func => (<sectionkey={func.name}id={func.name}className="api-section"><h3>{func.name}</h3><p>{func.description}</p><h4>参数</h4><table><thead><tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr></thead><tbody> {func.params?.map((param: any) => (<trkey={param.name}><td><code>{param.name}</code></td><td><code>{param.type}</code></td><td>{param.required ? '✅' : '-'}</td><td>{param.description}</td></tr> ))}</tbody></table> {func.example && (<><h4>示例</h4><pre><code>{func.example}</code></pre><buttononClick={() => handleTest(func.name, {})}> 🧪 在线测试</button></> )}</section> ))} {testResult && (<divclassName="test-result"><h4>测试结果</h4><pre>{testResult}</pre></div> )}</main> </div> );};9. 与Git工作流集成
// scripts/generate-docs.ts// 作为pre-commit hook自动生成文档import { execSync } from'child_process';import { readFileSync, writeFileSync } from'fs';import { globSync } from'glob';asyncfunctiongenerateAllDocs() {const tsFiles = globSync('src/**/*.ts');for (const file of tsFiles) {const code = readFileSync(file, 'utf-8');const parser = newCodeParser();const functions = parser.parseFile(code, file);if (functions.length === 0) continue;const generator = newDocGenerator(process.env.DOUBAO_API_KEY!);const doc = await generator.generateAPIDoc(functions, [], file);const md = generateMarkdownDoc(doc, file);const outputPath = file.replace('src/', 'docs/').replace('.ts', '.md');writeFileSync(outputPath, md, 'utf-8'); }// 自动提交文档execSync('git add docs/');console.log('✅ API文档已自动生成');}generateAllDocs();10. 总结
本文介绍了使用豆包AI构建API文档自动生成器的完整方案：
• AST解析：从TypeScript源码提取函数签名和类型 • AI文档生成：自动生成函数说明、参数表格和示例 • OpenAPI规范：生成标准Swagger文档 • Markdown渲染：美化的可读性文档 • 版本管理：文档变更追踪和CHANGELOG生成 • 交互式查看：带在线测试功能的文档页面
豆包AI让"写好代码即写好文档"成为现实，大幅降低了文档维护成本。
更多详细内容，请微信搜索"前端爱好者"， 戳我 查看 。