因为我们是异地对接接口文档,为此有对接文档是非常必要的,经过对比我选用swagger,但是node使用swagger有很多坑(细节)需要注意,我花费了两天时间才将文档展现出来,尤其是对注释部分需要严格按照格式去写。
我这里选用swagger-jsdoc和koa2-swagger-ui去实现。
首先我们在routes文件夹中另起一个文件swagger.js,为什么在routes文件下呢?因为在给到别人看文档的时候你是打开127.0.0.1:300/swaggger这样的网址的,所以它相当于node的其中一个路由。
下载依赖
npm install swagger-jsdoc koa2-swagger-ui
或
yarn add swagger-jsdoc koa2-swagger-ui
版本
配置文档
//swagger.js
const router = require('koa-router')()
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerDefinition = {
info: {
title: '你的文档标题',
version: '1.0.0',
description: '你的文档说明'
},
securityDefinitions: {
ApiKeyAuth: {
type: 'apiKey', // 类型
in: 'header', // 位置
name: 'token' // 参数
}
},
host: '127.0.0.1:300',//需要跟你node服务器地址一样
basePath: '/' // Base path (optional)
};
const options = {
swaggerDefinition,
apis: ['./routes/*.js'] // 写有注解的router的存放地址
};
const swaggerSpec = swaggerJSDoc(options)
// 通过路由获取生成的注解文件
router.get('/swagger.json', async function (ctx) {
ctx.set('Content-Type', 'application/json')
ctx.body = swaggerSpec
})
module.exports = router
在app.js文件引入路由
//app.js
const koaSwagger = require('koa2-swagger-ui')
//swagger配置
app.use(//注意这里需要看koa2-swagger-ui的版本 不然会报koaSwagger不是一个函数等错误
koaSwagger({
routePrefix: '/swagger', // host at /swagger instead of default /docs
swaggerOptions: {
url: '/swagger.json' // example path to json
}
})
)
此时页面是这样的:
接口注释
要想接口的路径和参数等信息出现在127.0.0.1:300/swagger页面上,需要在接口那协商注释;
swagger的注释是以@swagger开头的,方便swagger识别:下面以管理员接口为例
//admin.js
// #region
// #region可以将注释代码收缩
/**
* @swagger
* /admin/userLogin:
* post:
* summary: 管理员登录
* description: 管理员登录
* tags:
* - 管理员模块
* parameters:
* - name: name
* in: query
* required: true
* description: 账号
* type: string
* - name: password
* in: query
* required: true
* description: 密码
* type: string
* responses:
* 200:
* description: 成功获取
* schema:
* type: 'object'
* properties:
* code:
* type: 'number'
* data:
* type: 'object'
* description: 返回数据
* message:
* type: 'string'
* description: 消息提示
*/
// #endregion
这样一个比较完整的接口文档就出来了。页面上也会出现如下:
这样就可以将自己的接口文档输出到页面上了。下篇将介绍如何让远在他方的小伙伴调用本地的服务。
上一篇:token控制接口权限
下一篇:服务端图片上传和下载