feat: 完成 NestJS 后端核心底座开发 (M1-M6) 和 Ant Design Vue 前端迁移
主要更新: 1. 后端核心底座完成 (M1-M6): - 健康检查、指标监控、分布式锁 - 事件总线、队列系统、事务管理 - 安全守卫、多租户隔离、存储适配器 - 审计日志、配置管理、多语言支持 2. 前端迁移到 Ant Design Vue: - 从 Element Plus 迁移到 Ant Design Vue - 完善 system 模块 (role/menu/dept) - 修复依赖和配置问题 3. 文档完善: - AI 开发工作流文档 - 架构约束和开发规范 - 项目进度跟踪 4. 其他改进: - 修复编译错误和类型问题 - 完善测试用例 - 优化项目结构
This commit is contained in:
186
admin/docs/scripts/generate-api-docs.js
Normal file
186
admin/docs/scripts/generate-api-docs.js
Normal file
@@ -0,0 +1,186 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* API 文档自动生成脚本
|
||||
* 从后端 Swagger 自动生成前端文档
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const axios = require('axios');
|
||||
|
||||
// 配置
|
||||
const config = {
|
||||
backendUrl: process.env.BACKEND_URL || 'http://localhost:3000',
|
||||
docsDir: path.join(__dirname, '../src/wwjcloud/openapi/api'),
|
||||
apiGroups: {
|
||||
unified: {
|
||||
name: '统一 API',
|
||||
swaggerPath: '/docs-json',
|
||||
outputDir: 'unified',
|
||||
prefix: ''
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* 获取 Swagger JSON
|
||||
*/
|
||||
async function getSwaggerJson(group) {
|
||||
try {
|
||||
const url = `${config.backendUrl}${group.swaggerPath}`;
|
||||
console.log(`获取 ${group.name} API: ${url}`);
|
||||
const response = await axios.get(url);
|
||||
return response.data;
|
||||
} catch (error) {
|
||||
console.error(`获取失败: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成模块文档
|
||||
*/
|
||||
function generateModuleDoc(group, tag, paths) {
|
||||
const moduleName = tag.name;
|
||||
let markdown = `---
|
||||
title: ${moduleName} API
|
||||
description: ${tag.description || `${moduleName} 相关接口`}
|
||||
---
|
||||
|
||||
# ${moduleName} API
|
||||
|
||||
::: info ${moduleName}
|
||||
|
||||
${tag.description || `${moduleName} 相关接口`}
|
||||
|
||||
:::
|
||||
|
||||
## API 列表
|
||||
|
||||
`;
|
||||
|
||||
// 查找该标签下的接口
|
||||
Object.keys(paths).forEach(path => {
|
||||
Object.keys(paths[path]).forEach(method => {
|
||||
const operation = paths[path][method];
|
||||
if (operation.tags && operation.tags.includes(tag.name)) {
|
||||
markdown += generateApiDoc(path, method, operation);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
return markdown;
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成单个 API 文档
|
||||
*/
|
||||
function generateApiDoc(path, method, operation) {
|
||||
const summary = operation.summary || operation.operationId || '未命名接口';
|
||||
|
||||
let doc = `### ${summary}\n\n`;
|
||||
doc += `**接口**: \`${method.toUpperCase()} ${path}\`\n\n`;
|
||||
|
||||
if (operation.description) {
|
||||
doc += `**描述**: ${operation.description}\n\n`;
|
||||
}
|
||||
|
||||
// 请求参数
|
||||
if (operation.parameters && operation.parameters.length > 0) {
|
||||
doc += `**参数**:\n\n`;
|
||||
doc += `| 参数 | 类型 | 必填 | 说明 |\n`;
|
||||
doc += `|------|------|------|------|\n`;
|
||||
|
||||
operation.parameters.forEach(param => {
|
||||
const required = param.required ? '是' : '否';
|
||||
const type = param.type || param.schema?.type || 'string';
|
||||
doc += `| ${param.name} | ${type} | ${required} | ${param.description || ''} |\n`;
|
||||
});
|
||||
doc += `\n`;
|
||||
}
|
||||
|
||||
// 请求体
|
||||
if (operation.requestBody) {
|
||||
doc += `**请求体**:\n\n`;
|
||||
doc += `\`\`\`json\n`;
|
||||
doc += `{\n`;
|
||||
doc += ` // 请求数据\n`;
|
||||
doc += `}\n`;
|
||||
doc += `\`\`\`\n\n`;
|
||||
}
|
||||
|
||||
// 响应
|
||||
doc += `**响应**:\n\n`;
|
||||
doc += `\`\`\`json\n`;
|
||||
doc += `{\n`;
|
||||
doc += ` "code": 200,\n`;
|
||||
doc += ` "message": "success",\n`;
|
||||
doc += ` "data": {\n`;
|
||||
doc += ` // 响应数据\n`;
|
||||
doc += ` }\n`;
|
||||
doc += `}\n`;
|
||||
doc += `\`\`\`\n\n`;
|
||||
doc += `---\n\n`;
|
||||
|
||||
return doc;
|
||||
}
|
||||
|
||||
/**
|
||||
* 保存文档
|
||||
*/
|
||||
function saveDocument(outputPath, content) {
|
||||
try {
|
||||
const dir = path.dirname(outputPath);
|
||||
if (!fs.existsSync(dir)) {
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
fs.writeFileSync(outputPath, content, 'utf8');
|
||||
console.log(`已保存: ${outputPath}`);
|
||||
} catch (error) {
|
||||
console.error(`保存失败: ${error.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 主函数
|
||||
*/
|
||||
async function main() {
|
||||
console.log('开始自动生成 API 文档...\n');
|
||||
|
||||
for (const [key, group] of Object.entries(config.apiGroups)) {
|
||||
console.log(`处理 ${group.name}...`);
|
||||
|
||||
const swaggerData = await getSwaggerJson(group);
|
||||
if (!swaggerData) {
|
||||
console.log(`跳过 ${group.name}\n`);
|
||||
continue;
|
||||
}
|
||||
|
||||
const tags = swaggerData.tags || [];
|
||||
const paths = swaggerData.paths || {};
|
||||
|
||||
// 为每个标签生成文档
|
||||
for (const tag of tags) {
|
||||
const moduleName = tag.name.toLowerCase().replace(/\s+/g, '-');
|
||||
const content = generateModuleDoc(group, tag, paths);
|
||||
const outputPath = path.join(config.docsDir, group.outputDir, `${moduleName}.md`);
|
||||
saveDocument(outputPath, content);
|
||||
}
|
||||
|
||||
console.log(`${group.name} 完成\n`);
|
||||
}
|
||||
|
||||
console.log('API 文档生成完成!');
|
||||
console.log('访问: http://localhost:6173/wwjcloud/openapi/api/');
|
||||
}
|
||||
|
||||
// 运行
|
||||
if (require.main === module) {
|
||||
main().catch(error => {
|
||||
console.error('执行失败:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
|
||||
module.exports = { config, getSwaggerJson, generateModuleDoc };
|
||||
Reference in New Issue
Block a user