使用node生成swagger接口文档-阿里云开发者社区

开发者社区> 小周sir> 正文

使用node生成swagger接口文档

简介: 使用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.required required代表这个是必填项
  • 最重要的就是这两个@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就可以看到界面
在这里插入图片描述
通过发送请求,就可以看到我们请求的结果
在这里插入图片描述
以上就我们整体效果,只需我们只需增加模型,路由即可,就会自动生成接口文档描述

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
使用-MM生成include指令和依赖生成(make include directive and dependency generation with -MM)
I want a build rule to be triggered by an include directive if the target of the include is out of date or doesn't exist.
883 0
云服务器ESC的使用体验
阿里云服务器ESC的使用体验
32 0
怎么设置阿里云服务器安全组?阿里云安全组规则详细解说
阿里云服务器安全组设置规则分享,阿里云服务器安全组如何放行端口设置教程
7435 0
使用node+express+mongodb实现用户注册、登录和验证功能
使用node+express+mongodb实现用户注册、登录和验证功能
628 0
在使用蓝牙接口,遇到IOS下正常,Android下不正常的简易处理方法
如果遇到以上的情况怎么办,先确定下在调试的时候是否打开了调试面板, 如果有打开请关闭调试面板看是否还有问题,目前在安卓上打开调试面板是会有影响到蓝牙接口的使用,从之前遇到过这些问题的统计中也确实是因为这个原因
238 0
我的使用Esc体验
总体而言,在这个过程中,我体验到了服务器的神奇,也学习到了许多相关的知识,也希望在接下去的时间中继续进行相关的知识学习。
86 0
Node.js使用mongodb操作MongoDB数据库
Node.js使用mongodb操作MongoDB数据库
24 0
阿里云短信使用入门/开发接口文档一篇文章全搞定
阿里云短信提供秒级触达到达率99%,国际/港澳台短信覆盖200多个国家和地区,阿里云短信接入简单
3020 0
DMP文件的生成和使用
1、生成dmp的程序 #include   #pragma comment(lib,  "dbghelp.lib")//设置异常处理回调函数SetUnhandledExceptionFilter(UnhandledExceptionFilter);//异常处理代码//EXCEPTIO...
663 0
+关注
小周sir
面对过去,不要迷离;面对未来,不必彷徨;
51
文章
41
问答
文章排行榜
最热
最新
相关电子书
更多
文娱运维技术
立即下载
《SaaS模式云原生数据仓库应用场景实践》
立即下载
《看见新力量:二》电子书
立即下载