node的swagger现在也用上了注释型的文档，和java的有点类似。主要步骤就两个：swagger配置和注释生成文档
4.png
话不多说，直接开始
安装
// koa2-swagger-ui UI视图组件 swagger-jsdoc 识别写的 /***/ 转 json
npm install koa2-swagger-ui swagger-jsdoc --save
直接安装即可
配置
新建 swagger.js 文件，位置放哪都行，只要自己能找到，我放在了根目录，和 packages.js 同级
const router = require('koa-router')() //引入路由函数
const swaggerJSDoc = require('swagger-jsdoc')
const path = require('path')
const swaggerDefinition = {
info: {
title: 'blog项目访问地址',
version: '1.0.0',
description: 'API',
},
host: 'localhost:8000',// 想着改这里，如果不修改，那么接口文档访问地址为：localhost:8000/swagger
basePath: '/' // Base path (optional)
};
const options = {
swaggerDefinition,
apis: [path.join(__dirname, './routes/*.js')], // 写有注解的router的存放地址, 最好path.join()
};
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 中新增配置
const swagger = require('./swagger') // 存放swagger.js的位置，可以自行配置，我放在了根目录
const { koaSwagger } = require('koa2-swagger-ui')
// 接口文档配置
app.use(swagger.routes(), swagger.allowedMethods())
app.use(koaSwagger({
routePrefix: '/swagger', // 接口文档访问地址
swaggerOptions: {
url: '/swagger.json', // example path to json 其实就是之后swagger-jsdoc生成的文档地址
}
}))
启动项目，访问项目接口地址 + swagger ，我的地址是 http://localhost:8000/swagger
3.png
添加注释生成文档
1、学习 YAML 语言教程
2、根据 swagger 文档说明，添加注释
上代码 get 方式
// 获取博客列表
/**
* @swagger
* /api/blog/list:
* get:
* summary: 获取博客列表
* description: 获取博客列表
* tags:
* - blogs
* parameters:
* - name: author
* in: query
* required: false
* description: 作者
* type: string
* - name: keyword
* in: query
* required: false
* description: 搜索关键字
* type: string
* responses:
* 200:
* description: 成功获取
*/
router.get('/list', async (ctx, next) => {
const query = ctx.query
let author = query.author || ''
const keyword = query.keyword || ''
const listData = await getList(author, keyword)
ctx.body = new SuccessModel(listData)
})
post需要模板添加注释，如果无法加载 definition ，需要查看自己安装的版本
/**
* @swagger
* definitions:
* loginparam:
* properties:
* username:
* type: "string"
* default: "shangsan"
* description: 用户名
* password:
* type: "string"
* default: "123"
* description: 密码
*/
/**
* @swagger
* /api/user/login:
* post:
* summary: 登录
* description: 登录
* tags:
* - user
* consumes:
* - application/json
* - application/xml
* produces:
* - application/json
* - application/xml
* parameters:
* - name: body
* in: body
* schema:
* $ref: '#/definitions/loginparam'
* responses:
* 200:
* description: 发布成功
* 402:
* description: 信息填写不全
* 403:
* description: 参数类型错误
*/
router.post('/login', async (ctx, next) => {
如果觉得这样乱，注释都写在路由文件里面，可以单独摘出注释，单独写文件，我个人还是倾向于这样的方式，比较清晰，便于维护
上述配置完成后，访问localhost:8000/swagger，可能会一直转圈，访问不了，也可能会报错，如图
微信截图_20210813100220.png
很明显，相应的资源没有加载下来，cdn，时好时坏，那么就要把资源拿到本地：
所以就开始静态资源配置，找到相应资源为 koa2-swagger-ui 的 cdn 引用，将对应的资源拿到本地并配置修改：
微信截图_20210813101313.png
在 public 中新建文件为 swagger-ui ，将 图中几个文件放入文件夹中，在能访问时候将 cdn 文件拿下来，放入文件中，如图：
微信截图_20210813101700.png
这三个文件如果拿不到，可以私信我，一般每天早上会查看简书信息；
接下来修改 index.hbs 文件，把 cdn 文件换成本地文件地址就好了：
3333.png
然后修改 app.js 中的配置引用
// const { koaSwagger } = require('koa2-swagger-ui')
const { koaSwagger } = require('./public/swagger-ui')
然后保存，也可能需要重启项目，然后就可以访问了；
资源拿不到记得私信我；
