README.md

free-swagger

free-swagger 基于 free-swagger-core，提供 api，根据 swagger 文档全量生成前端接口代码并写入至项目文件

安装

npm i free-swagger -D

务必使用 -D 参数作为开发依赖，防止被 web 打包工具打包

生成 api 文件

项目使用

demo: https://github.com/yeyan1996/free-swagger-demo

// swagger.config.js
const freeSwagger = require("free-swagger");

freeSwagger("https://petstore.swagger.io/v2/swagger.json");

参数为 swagger 源，可以是 url，也可以是本地的 json 文件的相对/绝对路径

之后在 nodejs 中运行当前脚本

node swagger.config.js

或者绑定为 npm script

// package.json
"swagger": "node swagger.config.js"

npm run swagger

还可以接收一个对象，进行详细配置

// swagger.config.js
const freeSwagger = require("free-swagger");
const json = require("./swagger.json")

freeSwagger({
  source: json,
  header: "import http from './request'", // 假设请求库在 ./request
  lang: "js"
});

API

参数	说明	类型	可选值	默认值
source	必选，swagger 源（url/文件路径/json 文件）	string/json	-	-
cookie	可选，用于给作为 url 的 swagger 源鉴权的 cookie	string	-	-
root	可选，生成 api 的根路径	string	-	当前路径 + "/src/api"
header	可选，自定义头部代码	string	-	"import axios from 'axios'"
lang	可选，生成 api 语言	string	"js" / "ts"	"js"
jsDoc	可选，代码块附加 jsdoc 注释	boolean	-	true
templateFunction	可选，模版函数	(config:TemplateConfig): string	-	返回一个模版，用于自定义代码片段，参考底部示例
filename	可选，生成 api 的文件名	(name:string): string	-	name 为当前 swagger 中标注的 controller 名
typeOnly	可选，只生成 interface/typedef	boolean		false

TemplateConfig

见 free-swagger-core

默认模版

free-swagger 基于内置了默认模版用于生成 api 代码片段，具体见 free-swagger-core

生成 mock 文件

除了生成 api，free-swagger 还可以生成 mock 文件

输入一个 swagger 源，全量生成 mock 数据（json），配合其他 mock 工具实现本地 mock

额外生成了一个 mock.js 文件用于汇总所有 json，这使得 mock 工具只需引入一个 mock.js 即可实现本地 mock

注意：free-swagger 只输出 mock 文件，不提供本地 mock 服务

项目使用

demo: https://github.com/yeyan1996/free-swagger-demo

// swagger-mock.config.js
const { mock } = require("free-swagger");

mock("https://petstore.swagger.io/v2/swagger.json");

和生成 api 相同，传入 swagger 源

之后在 nodejs 中运行当前脚本

node swagger-mock.config.js

或者绑定为 npm script

// package.json
"mock": "node swagger-mock.config.js"

npm run mock

mock 功能同样支持详细配置

// swagger-mock.config.js
const { mock } = require("free-swagger");

mock({
  source: require("./swagger.json"),
  wrap:true
});

API

参数	说明	类型	可选值	默认值
source	必选，swagger 源（url/文件路径/json 文件）	string/json	-	-
cookie	可选，用于给作为 url 的 swagger 源鉴权的 cookie	string	-	-
mockRoot	可选，生成 mock 文件的根路径	string	-	当前路径 + "/mock"
wrap	可选，是否额外包裹一层标准接口返回格式 e.g {code:"200",msg:xxx,data:xxx}	boolean	-	false

常见问题

swagger 文档不规范，请检查参数格式

当前 swagger 源可能需要鉴权，free-swagger 提供了 cookie 选项，填入有权限的 cookie

或者直接将 swagger 源下载到本地，输入文件路径

使用 npm 形式安装后，打包工具报错

free-swagger 是 node 包，包含 node api，请勿在任何前端页面中使用！

某些接口的 mock 文件没有生成

不规范的 swagger 文档可能会导致部分 mock 数据丢失，free-swagger 会作出警告