主要分为express和koa2两个框架
由于node后端学习,得有一份接口文档,个人不是很喜欢swagger 本文主要在于避坑
一、网上科普文章多、此文主要解决遇到的问题
问题一：
SwaggerUIBundle is not defined 与 cdnjs.cloudflare.com CDN加载失败
这个原因网上找了很久没有答案 个人目前最好的解决办法 把静态资源拿到本地
先找到node_modules 如果是koa2-swagger-ui或 express-swagger-generator
或
修改index.html或index.hbs里引入地址 如下图：
koa2
express
github.com/swagger-api… koa2上图中引用的这几个文件找不到的 在这里dist里去拿
把这些文件放在public静态资源里 例如
koa2 在app引入public的位置
问题二：
koaSwagger is not a function
koa2-swagger-ui 高版本才能结构 低版本报错 低版本直接引入
问题三：
swagger设置端口一定要与项目端口保持一致
简洁版具体配置:一、 express-swagger-generator 配置
cnpm install express-swagger-generator
const expressSwagger = require('express-swagger-generator')(app);
const options = {
swaggerDefinition: {
info: {
description: '管理平台',
title: 'Swagger',
version: '1.0.0',
},
host: 'localhost:3002',
basePath: '/',//请求路径头
produces: [
"application/json",
"application/xml"
],
schemes: ['http', 'https'],
securityDefinitions: {
JWT: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
description: "",
}
}
},
route: {
url: '/doc',
docs: '/swagger.json'
},
basedir: __dirname,
files: ['./routes/*.js']
};
expressSwagger(options);关于注释
/**
* @typedef UserJSON
* @property {string} username.required - 请输入用户名 - eg: 1
* @property {string} password.required - 请输入密码 - eg: 1
*/
/**
* @typedef Error
* @property {string} code.required
*/
/**
* 用户登陆
* @route POST /users/login
* @summary 登陆
* @group user - 用户相关API
* @param {UserJSON.model} body.body.required - username&password
* @returns {object} 200 - 成功
* @returns {Error} default - Unexpected error
*/简洁版具体配置:二、koa2-swagger-ui 配置
npm install koa2-swagger-ui
npm install swagger-jsdoc新建文件swagger.js 位置根据自己放
const router = require('koa-router')(); // 引入路由函数
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerDefinition = {
info: {
description: '关于API文档',
version: '1.0.0',
title: 'Koa2_server Swagger',
},
host: 'localhost:4000',
basePath: '/', // Base path (optional), host/basePath
schemes: ['http', 'https'],
securityDefinitions: {
server_auth: {
type: 'oauth2',
description: '登录账号密码鉴权',
tokenUrl: 'http://localhost:4000/image/oauth',
flow: 'password',
scopes: {
token: 'modify pets in your account'
}
},
}
};
const options = {
swaggerDefinition,
// 写有注解的router的存放地址(当你新增swagger时文档里没显示出来的话那么就是这边地址没有加进去)
apis: ['./routes/*.js'] // routes下所有的js文件
};
const swaggerSpec = swaggerJSDoc(options);
// 通过路由获取生成的注解文件
router.get('/swagger.json', async ctx => {
ctx.set('Content-Type', 'application/json');
ctx.body = swaggerSpec;
});
module.exports = router;
// 将页面暴露出去appjs里引入上面js文件，如果报问题一的错误 把这引用地址替换
const swagger = require('./config/swagger')
const { koaSwagger } = require('./public/swagger-ui')//这个地址是出现问题一后 静态文件放的位置
app.use(swagger.routes(), swagger.allowedMethods())
app.use(
koaSwagger({
routePrefix: '/swagger', // 这里配置swagger的访问路径
swaggerOptions: {
url: '/swagger.json', // 这里配置swagger的文档配置URL，也就是说，我们展示的API都是通过这个接口生成的。
},
}),
);
