shuwenkai
新手
新手
  • 最后登录2019-09-27
  • 发帖数4
  • 社区居民
阅读:169回复:0

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,如果后续上传我会再更改文章,文笔不好多见谅,如有写的不对的地方欢迎指正

最新喜欢:

阿尔卑斯丶阿尔卑斯丶
游客


返回顶部