vue 3 项目不自动生成接口文档，需组合 mock 工具与 swagger 解析实现本地模拟服务启动和文档结构加载；通过 mockjs 拦截请求、axios 发起调用、swagger-jsdoc 解析文档，提升前端开发效率。
Vue 3 项目本身不直接“自动生成接口文档”，Mock 工具（如 mockjs）只负责拦截请求、返回模拟数据，它不生成文档；而接口文档（如 Swagger/OpenAPI）需由后端提供或通过工具从代码注解中提取。但你可以通过组合 Mock + 文档解析工具，在初始化阶段完成「本地模拟服务启动」和「文档结构加载」两个动作，为前端开发提供可查、可调、可联的闭环体验。
安装必要依赖
在 Vue 3 项目初始化完成后，执行以下命令：
- mockjs：用于定义和拦截模拟接口
- axios：统一发起请求（Mock 拦截基于 xhr/fetch，与 axios 兼容）
- swagger-jsdoc（仅 dev 环境）：解析后端提供的 Swagger JSON 或本地注释，生成类型/文档元数据
命令示例：
npm install mockjs axios --save<br>npm install swagger-jsdoc --save-dev
配置 Mock 服务并自动注册
在 src/mock/index.js 中集中管理所有模拟规则，并支持模块化引入：
- 创建
src/mock目录，新建index.js - 使用
require.context自动加载子模块（如user.js、article.js），避免手动 import - 调用
Mock.mock()绑定路径、方法与响应数据
示例（src/mock/index.js）：
import Mock from 'mockjs';<br>Mock.setup({ timeout: '200-600' });<br><br>const modules = require.context('.', false, /\.js$/);<br>modules.keys().forEach(key => {<br> if (key === './index.js') return;<br> modules(key).default?.();<br>});
再比如 src/mock/modules/user.js：
import Mock from 'mockjs';<br>export default () => {<br> Mock.mock('/api/user/list', 'get', {<br> code: 200,<br> data: { list|5: [{ id|+1: 1, name: '@cname', email: '@email' }] }<br> });<br>};
加载 Swagger 文档用于类型推导与文档参考
如果后端已部署 Swagger JSON（如 /swagger.json），可在项目启动时拉取并缓存结构，不用于运行时 Mock，而是辅助开发：
- 新建
src/api/swagger.ts（或 .js），用 axios 获取 JSON 并导出为常量 - 配合 VS Code 插件（如 OpenAPI Generator）或脚本，将 JSON 转为 TypeScript 接口定义（
src/types/api.d.ts） - 该步骤不参与构建，仅在开发阶段提升类型安全与 IDE 提示
示例（src/api/swagger.ts）：
import axios from 'axios';<br><br>export const SWAGGER_URL = 'https://your-api.com/swagger.json';<br><br>export async function loadSwaggerSpec() {<br> try {<br> const res = await axios.get(SWAGGER_URL);<br> return res.data;<br> } catch (e) {<br> console.warn('Failed to load Swagger spec, using fallback');<br> return { paths: {}, components: {} };<br> }<br>}
在入口文件启用 Mock 并可选注入文档上下文
在 main.js / main.ts 中引入 Mock 配置即可激活拦截：
import './mock'; // 启动所有 mock 规则<br>// 可选：挂载 swagger spec 到全局供调试面板使用<br>if (import.meta.env.DEV) {<br> import('./api/swagger').then(({ loadSwaggerSpec }) => {<br> loadSwaggerSpec().then(spec => {<br> (window as any).__SWAGGER_SPEC__ = spec;<br> });<br> });<br>}
此时打开浏览器控制台，输入 window.__SWAGGER_SPEC__.paths 即可查看接口路径列表，相当于一个轻量级本地文档视图。
不复杂但容易忽略：Mock 和文档是两层能力——Mock 解决“有没有数据”，文档解决“数据长什么样、怎么调”。把它们在初始化阶段串起来，前端就能一边写页面，一边查结构、试参数、看响应格式，真正实现脱离后端高效推进。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
