使用node生成swagger接口文档

在开发过程中,我们请求的接口的时候,往往都是后台我们一个接口文档,便于我们查阅,今天我们就用node生成一个自己的接口文档 ,知道接口文档怎么来的。

  • 这里不在讲解node怎么安装,接口怎么写,直javascript菜鸟教程接写API接口文档生成的那部分,如果想看怎么使用node接口的话,可以移动到https://blog.csdn.net/Govern66/article/details/1javascript菜鸟教程04290198这篇博客
  • 最终案例我已经上传gi阿飘军人老公二爷thub中https://github.com/MrZHLF/node-express-swagger.git,可以下载看看

安装swagger插件

cnpm install  express-swagger-generator

在你的app.js文件引入

const expressSwagger = require('express-swagger-generator')(app)

使用,其中files就是你api接口文件路径,我这里是router下面的api里面js文中间件是什么意思

  • host端口号,要和自己启动的node服务保持一致
  • route 访问的地址
  • files 访问api接口地址
let options = {
swaggerDefinition: {
info: {
description: 'This is a sample server',
title: 'Swagger',
version: '1.0.0'
},
host: 'localhost:3000',
basePath: '/',
produces: ['application/json', 'application/xml'],
schemes: ['http', 'https'],
securityDefinitions: {
JWT: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
description: ''
}
}
},
route: {
url: '/swagger',
docs: '/swagger.json' //swagger文件 api
},
basedir: __dirname, //app absolute path
files: ['./router/api/*.js'] //Path to the API handle folder
}
expressSwagger(options)

在你的api接口文件中定义

  • @route 请求接口的地址
  • @param请求参数 ,有几个参数写多少个,username.query.required requir中间件软件有哪些ed代表这个是必填项
  • 最重要的就是这两个@rou中间件软件有哪些te和@param,一定要按中间件是什么照这样api接口的格式去写
  • userRegisterPost需要把这个抛出去,其api地方可javascript浏览器以接收到。
/**
* 用户信息注册
* @route POST /api/users/register
* @group user - Operations about user
* @param {string} username.query.required - 请输入用户名
* @param {number} password.query.required - 请输入密码
* @param {string} email.query.required - 请输入合法邮箱
* @returns {object} 200 - An array of user info
* @returns {Error}  default - Unexpected error
*/
exports.userRegisterPost = function(req, res) {
console.log(req)
// 查询邮箱是否注册
res.setHeader('Content-Type', 'application/json;charset=utf-8')
User.findOne({
email: req.query.email
})
.then(user => {
if (user) {
// 邮箱已经注册了
return res.status(400).json('邮箱已经被注册')
} else {
// 生成默认头像
const avatar = gravatar.url(req.query.email, {
s: '200',
r: 'pg',
d: 'mm'
})
const newUser = new User({
username: req.query.username,
password: req.query.password,
email: req.query.email,
avatar
})
// 对密码加密
bcrypt.genSalt(10, function(err, salt) {
bcrypt.hash(newUser.password, salt, (err, hash) => {
if (err) {
throw err
}
// 密码加密
newUser.password = hash
newUser
.save()
.then(user => {
res.json(user)
})
.catch(err => {
console.log(err)
})
})
})
}
})
.catch(err => {
console.log(err)
})
}

定义接口文档之后,需要在我们的api.js使用
引入路由模型

const user = require('./router/api/user')

使用router中间件

  • api/users/javascript:void(0)registejavascript什么意思和我接口api路径保持一致
app.post('/api/users/register', (req, res) => {
user.userRegisterPost(req, res)
})

当我们浏览器访问h中间件的主要作用和功能ttp://localhost:3000/swagger就可以看到界面

使用node生成swagger接口文档


通过发送请求,就可以看到我们请求的结果

使用node生成swagger接口文档


以上就我们整体效果,只需我们只需增加模型,路由即可,就会自动生成接口文档描述