Auto-Swagger

auto-swagger是一个爬取swagger-ui并生成申请接口文件的命令行工具，旨在帮忙接口调用者一键生成接口代码文件。

传送地址：https://github.com/pablezhang/auto-swagger

为什么要做auto-swagger？

在工作中，通常后盾开发同学会提供一份swagger接口文档。前端同学每次查问该文档调用某个接口。相当于，咱们从swagger-ui上摘录接口应用办法，设想大家在开发过程中是否遇到过以下问题：

  1. 调用接口发现接口报404，费神费劲查看发现把单词拼错了~
  2. 调用接口发现接口报400，认真比照swaager发现参数类型写错、参数名称写错~
  3. 一时粗心把申请类型写错了~
  4. ....

    如果在工作中你也遇到过上述问题，或者心田会指摘本人的粗枝大叶，同时有一点的心累0.0。开发者在swagger-ui文档中抄录接口时都会可能会抄错接口的url、参数类型、参数名称等等。尤其，开发同学有可能在赶我的项目进度、面对swagger-ui接口数量大、文档不标准等问题时出错的几率会更大。
    auto-swagger正是为解决上述机械反复的swagger抄录工作而呈现的。

如何应用

1、装置auto-swagger

npm install auto-swagger -g 或 yarn add auto-swagger -g

2、增加配置文件swagger.config.js

如果你是第一次应用，倡议你应用初始化配置命令。关上命令行工具 auto-swagger init 此时，你的目录下应该会有一个swagger.config.js文件

// swagger-url地址，找到返回次要json的申请const urlAddress = 'http://your-swagger-url/v2/api-docs';// 想要输入的swaager接口文件寄存的门路，请应用相对路径。const outputPath ='Services';// 指定过滤掉某些参数，这些参数通常因为是专用的缘故，不须要每个接口中都传值const excludeParamName = [ "Application-Key", "Access-Token", "extFields"];const config = { excludeParamName, outputPath, url: urlAddress};module.exports = config;

上述代码，是一个简略配置的swagger.config.js文件

3、开始获取swagger-ui的接口文件

执行上面的命令

auto-swagger run

此时，你会发在你指定的outputPath中会多了一些SomeService文件，这些文件即为接口调用文件。 到此，根本的用法曾经实现了

如何在我的项目中集成auto-swagger生成的接口文件？

先看下的生成的接口文件长什么样子, 此处应用了一个公共的swagger地址：http://petstore.swagger.io/

//Operationsaboutuser.ts/** * @Description: User */  /** 留神Request为自行封装的ajax申请文件，须要自行实现。 */import Request from 'utils/Request';class Operationsaboutuser {  /** * 接口简介 This can only be done by the logged in user. * 接口备注 This can only be done by the logged in user. * 接口类型 post * 接口地址 /user * @param body [object Object] Created user object */ public async createUser ({body}) { return Request({ url:`/user`, method:'POST', data: body, query: {}, app: 'user', }) } }// 默认将每一个Controller作为一个文件，并以Controller名称作为单例类的名称export default new Operationsaboutuser

如何在我的项目中应用这些接口文件？

第一步，须要自行实现Request文件。其可能须要反对几个必选参数
1、url:即swagger申请门路
2、method: "POST" | "GET" | "DELETE" | "PUT"等你须要反对的办法
3、data: 通常是POST与PUT办法才有
4、query: 查问参数
咱们下面说其可能反对这几个参数，是因为Request是你本人实现的。你能够齐全自主的决定形参。

第二步、调用
察看上述文件，发现接口办法被封装在了一个单例中,因而应用时也极其简略

import Operationsaboutuser from 'Services/Operationsaboutuser';async function  createBody(body) { const {resultCode, resultMsg} =  await Operationsaboutuser.createUser({body}) if(resultCode === "0"){ console.log("新建胜利") }}createBody({id: "123", name: "foo"}) // 新建胜利

如何自定义接口文件格式，以集成到已有的我的项目。例如我的项目中已有Request.js，但文件不在utils中，而且因为某些起因你不能批改这些历史代码。 auto-swagger能够自定义生成接口文件的形式，残缺配置如下

  1. url: string：swagger-ui中json信息接口
  2. outputPath: string：以swagger.config.js所在文件夹为根目录，指定要输入接口文件到指定的门路
  3. excludeParamName: string[]：须要过滤掉的参数，如Application-key、token等每个接口中都须要的参数，不用再在每个接口文件参数中体现。
  4. childFunTemplate: string： 每个接口函数的模板字符串。默认值如下所示
const childFunTemplate = ` /**</childInfo/></childParams/> */ public async </childFunName/> ({</childrenParams/>}) { return Request({ </childrenUrl/>, method:</childrenMetHod/>, data: </childrenName/>, query: {</QueryNames/>}, app: 'user', }) }`;

5 . parentFunTemplate: string： 每个接口文件的配置字符串。默认值如下

const parentFunTemplate = `/** * @Description: </FileDescription/> */import Request from 'utils/Request'; //此处能够批改为指定的Request文件class </parentFunName/> { // 也能够去掉不封装为，单例模式、 </childFunList/>}export default new </parentFunName/>`;