vue 自动生成swagger接口请求文件的方法

下面是详细讲解 "Vue 自动生成 Swagger 接口请求文件的方法" 的完整攻略。

什么是 Swagger？

Swagger 是一种用于编写 RESTful API 接口文档的工具，它可以生成 API 文档、客户端 SDK 和服务器代码。目前，Swagger 已经成为了 API 文档编写的事实标准。

Vue 自动生成 Swagger 接口请求文件的方法

步骤如下：

1. 安装 swagger-jsdoc 和 jsdoc-to-markdown

bash
npm i swagger-jsdoc jsdoc-to-markdown --save-dev

swagger-jsdoc：支持 JSDoc 注释格式的 Swagger 解析器。

jsdoc-to-markdown：将 JSDoc 注释转换成 Markdown 格式的工具。

1. 创建 swagger.json 文件

在项目的根目录下创建一个名为 swagger.json 的文件，用于编写 API 文档。

示例内容：

json
{
"swagger": "2.0",
"info": {
"title": "APIs",
"version": "1.0.0"
},
"basePath": "/v1",
"schemes": ["http"],
"consumes": ["application/json"],
"produces": ["application/json"],
"paths": {
"/users": {
"get": {
"tags": ["User"],
"description": "获取用户列表",
"responses": {
"200": {
"description": "返回用户列表",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/User"
}
}
}
}
}
}
},
"definitions": {
"User": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}

1. 编写 JSDoc 注释

在项目中编写 JSDoc 注释，并按照 Swagger 规范编写注释。

示例：

js
/**
* 获取用户列表
* @summary 获取用户列表
* @return {array<User>} 200 - 用户列表
*/
export function getUsers() {}

1. 编写 npm script

在 package.json 文件中添加一个 npm script，用于生成 API 请求文件。

示例：

json
{
"scripts": {
"generate-request": "jsdoc2md {path}/src/**/*.{vue,js} | node {path}/bin/swagger.js --swaggerOutputFile {path}/swagger.json"
}
}

1. 生成 API 请求文件

运行以下命令，生成 API 请求文件：

bash
npm run generate-request

当命令执行完成后，在项目的根目录下就会生成一个名为 swagger.json 的文件，它是自动生成的 API 请求文件。

1. 自动生成 API 请求文件

使用了 Step1 到 Step5 后，您就已经成功的准备了一切所需工具。但是每次要手动运行 npm run generate-request 同步 API 到文档真的很麻烦。我们可以利用 IDE 的 Plugin 或者 Git Hook 来自动生成 API 请求文件。

示例：

在使用 WebStorm IDE 的同学可以安装 Swagger Plugin 插件用于实时更新API对象。除 WebStorm 外的情况参考 Github 的 pre-commit-template（在提交代码前扫描增删API）或 post-checkout-template（切换分支后实时同步 API）等 Git Hook 来自动生成 API 请求文件。

总结

以上就是使用 JSDoc 注释结合 Swagger 规范编写 API 文档，通过 Swagger 解析器自动生成 API 请求文件的完整攻略。这种方式可以提高编写 API 文档的效率，避免手工编写 API 请求文件带来的错误，提高代码的整洁性和可读性，强烈建议在 Vue 项目中使用。