阅读 616

一步一步教你Koa2编写接口文档(后续)

前言


寻找资料

因为看官网的例子,报错后:

开始尝试百度、谷歌搜索、掘金、甚至连腾讯课堂、慕课网、群里都搜索咨询过,仍然没有任何回应,正当我快要放弃的时候,我从百度搜索看到很后的文章,看到Git有一篇叫Koa2-Swagger 服务器脚手架,看介绍有koa-swagger-decorator的字眼,一言不合就下载下来看看,终于皇天不负有心人,找到正确的写法了。

Start Handle

install

npm i koa-swagger-decorator --save-dev
复制代码

新建文件 swaggerDec.js

const { SwaggerRouter } = require('koa-swagger-decorator');
const path = require('path')
const router = new SwaggerRouter();

// swagger docs avaliable at http://localhost:3333/swagger-html
router.swagger({
    title: '排课系统',
    description: 'API DOC',
    version: '1.0.0'
});
// 查找对应目录下的routes文件夹
router.mapDir(path.resolve(__dirname, '../routes/'));

module.exports = router
复制代码

在 app.js 中引入

require("babel-register");
const swaggerDec = require('./config/swaggerDec');

app.use(swaggerDec.routes(), swaggerDec.allowedMethods())
复制代码

记得要引入 babel-register,才可以支持es7装饰器的语法,详情安装使用请移步到一步一步教你Koa2编写接口文档(不写接口文档的后端不是好后端)

接着我进行测试,新建一个 test.js

14.png

然后熟练的在 app.js 引入 test.js

require("babel-register");
const swaggerDec = require('./config/swaggerDec');
const test = require('./routes/test') 

app.use(swaggerDec.routes(), swaggerDec.allowedMethods())
app.use(test.routes(), test.allowedMethods())
复制代码

我们来看看,能不能显示我们的 swagger

访问:http://localhost:3333/swagger-html

14.png

如果不出所料,应该可以看到我们定义的 GET /featuresDev/ 接口

咦,可以看到 swagger 已经正常显示了,虽然接口不出来,但已经很欣慰了,毕竟不会报错了,于是我觉得可能是路径写的有问题。

检查。

15.png

我们的接口写在 routes 文件夹下。

可以看到,我们的 router.mapDir(path.resolve(__dirname, '../routes/')) 并没有写错,是对的。

经过很慢长的排查、检查、搜索,最终是因为语法写错了。(就知道)

首先,我们的 swaggerDec.js 写法正确!

其次,app.js 并不用引入 test.js

为什么?

因为我们的 swaggerDes.js 已经扫描了 routes 文件夹下的接口,所以不需要在单独在引入。

test.js 文件只需要导出 class

什么意思?

就是把接口和装饰器(接口文档写法)写在class里面的方法中。

17.png

增删改查如上,看成效。

18.png

真的不容易,终于把接口文档搞明白了。

搞了一天了,山穷水复疑无路,柳暗花明又一村啊!

接下来可以好好整顿我的 音乐博客 的接口文档了,Year!

代码源码请戳一戳!

Tips —— babel

正如所见,该 koa-swagger-decorator 会使用装饰器语法,那我们需要安装使用 babel

Install Babel

npm i babel-cli babel-core babel-plugin-transform-decorators-legacy babel-register --save-dev
复制代码

新建 .babelrc 文件

{
    "presets": [],
    "plugins": [
        "transform-decorators-legacy"
    ]
}
复制代码

成功配置下,即可使用装饰器语法。

最后

为什么我一定要研究 koa-swagger-decorator,因为用 swagger-jsdoc 写的注解东西实在是太多了,等下整个文件一打开都是这些注解,为了写接口文档,所以能用注解装饰器还是用,代码可观性会得以提升!

当然,我们在用一个东西的时候,不可能一下子就会用、就会写,遇到困难不要怕,可怕的是你还没有去做、去做到无能为力。几时我也是快放弃了,最后还不是找到解决方法了。

这是入团委的时候,墙上的字:

坚持到无能为力,奋斗到感动自己。

也送给大家。

好像写了很多无关技术的话,哈哈哈,可能是我真的是有感而发,太激动了!

花絮

看累了吧,各位兄弟们,给大家看个有趣的东西

19.jpg

穷追不舍呀,我都说我随便写的,还疯狂拉着我追问。

参考文章

Koa2-Swagger 服务器脚手架

以往推荐

一步一步教你Koa2编写接口文档(不写接口文档的后端不是好后端)

Vue-Cli3搭建组件库

Vue实现动态路由(和面试官吹项目亮点)

项目中你不知道的Axios骚操作(手写核心原理、兼容性)

VuePress搭建项目组件文档

koa2+vue+nginx部署

vue-typescript-admin-template后台管理系统

原文链接

juejin.cn/post/694944…

文章分类
后端
文章标签