使用node生成swagger接口文档

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

• 这里不在讲解node怎么安装，接口怎么写，直接写接口文档生成的那部分，如果想看怎么使用node接口的话，可以移动到https://blog.csdn.net/Govern66/article/details/104290198这篇博客
• 最终案例我已经上传github中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.requiredrequired代表这个是必填项
• 最重要的就是这两个@route和@param,一定要按照这样的格式去写
• userRegisterPost需要把这个抛出去，其api地方可以接收到。

/**
 * 用户信息注册
 * @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/registe要和我接口api路径保持一致

app.post('/api/users/register', (req, res) => {
  user.userRegisterPost(req, res)
})

当我们浏览器访问http://localhost:3000/swagger就可以看到界面

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

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