nodejs后台学习之路--集成swagger

楼主^#

更多发布于：2019-09-26 11:40

   相信不管是前端还是后端的朋友都对swagger不陌生，java的swagger生态很完善了，也是方便许多，但是对于前端的小哥们来说可能新学习一门语言成本太高，又想自己对代码有一个记录，生成一目了然的swagger接口文档就方便许多，小弟也是一路摸索，做的不对的地方欢迎在评论指正！

   首先我们需要的是搭建一个nodejs的服务器（推荐使用koa或者express框架，本篇文章基于express4的基础集成了swagger，因为koa2并不熟悉的原因，目前没有这方面学习计划，所以就不写关于koa的），当然，已经看到这里相信也已经是会express的，搭建服务器就不多赘述了，直接开始正题。
   服务器搭建好了之后，需要下载express-swagger-generator依赖模块，

npm i express-swagger-generator --save-dev

下载好之后就是常规的引入了，注意这里是require引入哦

let express = require("express");
let app = express();
const expressSwagger = require("express-swagger-generator")(app);

最重要的部分来了！！！！，引入依赖之后需要配置json

let options = {
  swaggerDefinition: {
    info: {
      description: "这是swagger的描述文件",
      title: "这是标题",
      version: "1.0.0" //版本号
    },
    host: "localhost:8888", // baseapi 访问地址+端口
    basePath: "/v2",// baseapi文件夹
    produces: ["application/json", "application/xml"],
    schemes: ["http", "https"],
    securityDefinitions: {
      JWT: {
        type: "apiKey",
        in: "header",
        name: "Authorization",
        description: ""
      }
    }
  },
  route: {
    url: "/swagger", // 访问swagger的地址
    docs: "/swagger.json" //swagger文件 api
  },
  basedir: __dirname, //app绝对路径
  files: ["./controller/*.js"] //api扫描文件的路径
};
expressSwagger(options);

关于配置中的参数我也做了说明，特别需要注意的是route对象下面的url，就是你访问swagger的地址哦，
比如本文我搭建的服务器在本地，端口为8888，所以我的地址为localhost：8888/swagger，files数组配置的就是api扫描的文件路径了，我在这里是配置的是扫描controller文件夹下面的所有js文件（关于有的朋友喜欢在router路由处写注释扫描也是可以的，只需要修i该你需要扫描的文件路径就好），具体访问效果，因为图片上传不是很方便，就略去拉！
   最后一步也就是关于注释写法，看了官网的api，写出一下个人的理解

/**
* @typedef UserRes
* @property {integer} msg - 描述内容
* @property {string} color - 随便写的
* @property {string} password.require - 用户密码 require为必填，如果在请求参数中需要使用model，需要写成 model名.body
* @property {string} name - 用户名
*/

/**
* @route GET /userInfo
* @group foo
* @param {string} password.require - 用户密码
* @param {string} name.required - 用户名
* @returns {UserRes.model} 200 - 用户信息数组
* @returns {Error} error - Unexpected error
*/
exports.userInfo = (req, res) => {
  console.log("test api 收到请求");
  let sendMessage = {
   msg:'msg',
   color:'#333',
   ...req.query
  };
  res.send(`您收到了${JSON.stringify(sendMessage)}`);
}

   @typeof那一块是定义的一个model，在后续的@returns {UserRes.model} 200 - 用户信息数组有使用到

具体页面效果如图

图片：2.png

图片：1.png

这就是本片文章的全部内容拉，关于源码链接的问题，因为代码并不多，所以没有上传GitHub，如果后续上传我会再更改文章，文笔不好多见谅,如有写的不对的地方欢迎指正

喜欢1

nodejs后台学习之路--集成swagger

最新喜欢：