Aomi-yapi-convert NPM

aomi-yapi-convert

针对yapi文档转js或者ts文件的自动化npm插件

演示地址

功能体验地址: http://yapi.theapi.world/

功能

支持转ts、js API文件
js文件支持jsDoc版本和simple注释版本
ts文件支持Ts版本和simple注释版本
支持自定义配置生成api文件位置
支持自定义配置axios路径和axiosName来配置个人封装的请求框架
支持自定义配置baseUrl,不配置默认取项目的baseUrl(服务端不一定会有)
支持自定义配置生成api文件名
支持增加任意自定义形参及默认值
支持根据个人风格偏好选择导出文件导出的格式

这个工具能帮你做些什么？

帮你完成交互搬运工作
减少你经常搬运错误的情况
获得来自后台同事为你写的字段以及参数提示，不用频繁来回切文档页面去看文档
获得来自axios的配置提示，避免老是忘记配置项参数要去看文档的问题
api文件即是注释，api文件即是文档，获得良好的开发体验
具备让你代码联调之前，只要API文档出来了，你的代码就具有获得具体字段名称的能力

安装

Using npm:

$ npm install aomi-yapi-convert --save-dev

Using yarn:

$ yarn add aomi-yapi-convert -D

怎么使用

如果不想在package.json里面添加额外的script,可以在终端运行下方命令，会自动触发交互命令行，生成配置文件

$ npx aomi-yapi-convert

虽然上面的命令也能满足使用，但是毕竟不方便也不太好记，每次更新都要打一遍，还是推荐在项目package.json添加script:

 "scripts": {
    "build:api": "aomi-yapi-convert",
  },

首次构建本地配置文件，会询问你几个问题，然后作为依据来生成配置文件（配置文件推荐将其添加为gitignore文件。不会干扰其他开发人员开发，特别是项目大的时候，每个人的对应的项目加起来配置文件将会很长。）

下面开始来解释一下几个有必要的问题，以及需要的输入：

请输入yapi地址(含projectId)：这个只需要粘贴yapi的具体项目地址过来就可以了
请粘贴yapi token(打开网站network 接口header可看)：这个token是api请求携带的token.可以通过接口请求header看或者看网站的cookie。截图如下：

you need proxy to see the image

或者

you need proxy to see the image

请输入yapi userId (打开网站network 接口header可看_yapi_uid值)：token和userId对应，否则登录状态将会失效

以添加script为示例，我们看下实际生成的效果

you need proxy to see the image

然后你就会发现在根目录会生成一个api.config.json的配置文件。目前暂时的配置约定是这样的

Api配置

参数名称	类型	默认值	备注
protocol	string		协议头https: 或http: 由文档地址决定
host	string		example: baidu.com
version	string		typescript(ts)	javascript(js) 两种版本，type类型分别是TsType类型和jsdoc类型
axiosFrom	string	import fetch from 'axios'	这里配置自定义的请求目录，考虑到大部分时候我们都用axios的包，所以使用axios作为默认请求，你也可以使用自定义的请求。
axiosName	string	fetch	这里配置自定义的请求Name,这里改成ssr的this指针挂载方式
dataParseName	string	detailMsg	这里配置服务端统一返回的数据结构开始序列的对应key信息
isNeedType	boolean	true	这里设置是否需要js doc类型，建议设置为true。会有非常完善的提示，来自后台的配置注释我迁移过来了
isNeedAxiosType	boolean	true	这里设置是否需要axios的插件提示，默认为false, 如果设置为true, axios的额外配置项的类型提示将会是插件引入的axios提示.
isNeedSecondType	boolean	false	可以设置true将Ts interface 里面的对象类型拆分其他interface方便引用
customerSnippet	string[]		用户自定义片段，字符串数组，每项占据一行
customer	Array<{name: string, default: ''}>		这里设置自定义的参数类型，该类型会添加进入请求的形参,支持传入任意数量形参，建议使用project里面的来定义，可能存在同一个项目调用不同的业务线api的情况
outputStyle	string	defaultExport	支持值defaultExport, nameExport, anonymousExport,分别对应了默认导出，具名导出，匿名函数导出
projects	project[]		project配置见下表

Project 配置

参数名称	类型	备注
projectId	number	项目id
outputDir	string	统一的文件生成路径，请注意默认文件夹是src/api目录，如果该目录下已经有文件了，建议在该目录起一个子目录名称：ep: src/api/auto/.
isLoadFullApi	boolean	这里配置是否全量加载api文件，原有项目已经有api的文件，请设置为false局部更新，全量更新会生成重复代码，徒增冗余
hideUnDoneApi	boolean	这里配置是否加载服务端接口显示未完成的Api。开发期间Api接口可能还是未完成状态。方便前端调试,默认加载。
prefix	string	一般该项设置为空，但我注意到部分接口服务端不配置服务名（比如超市的接口），需要前端手动添加，所以加了该配置项。这个配置项加了之后会在该项目组下所有接口添加这个字符串
customer	Array<{name: string, default: ''}>	这里设置自定义的参数类型，该类型会添加进入请求的形参,支持传入任意数量形参，不设置会默认继承全局的。
group	Array<{catId: number, outputDir: string, fileName: ''}>	{ catId: 后台项目下的菜单id outputDir: 可以自定义生成文件路径，不设置继承project的路径 fileName: 如果不喜欢程序生成的文件名可以自定义文件名 }