7

关于node koa2和express框架搭建swagger

 1 year ago
source link: https://blog.51cto.com/u_16174484/6868699
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

主要分为express和koa2两个框架

由于node后端学习,得有一份接口文档,个人不是很喜欢swagger 本文主要在于避坑

一、网上科普文章多、此文主要解决遇到的问题

关于node koa2和express框架搭建swagger_json

SwaggerUIBundle is not defined 与 cdnjs.cloudflare.com CDN加载失败

这个原因网上找了很久没有答案 个人目前最好的解决办法 把静态资源拿到本地

先找到node_modules 如果是koa2-swagger-ui或 express-swagger-generator

关于node koa2和express框架搭建swagger_json_02
关于node koa2和express框架搭建swagger_API_03

修改index.html或index.hbs里引入地址 如下图:

关于node koa2和express框架搭建swagger_API_04
express
关于node koa2和express框架搭建swagger_json_05

 github.com/swagger-api… koa2上图中引用的这几个文件找不到的 在这里dist里去拿

关于node koa2和express框架搭建swagger_Node.js_06

把这些文件放在public静态资源里 例如

关于node koa2和express框架搭建swagger_API_07

koa2 在app引入public的位置

关于node koa2和express框架搭建swagger_API_08

关于node koa2和express框架搭建swagger_json_09

koaSwagger is not a function

koa2-swagger-ui 高版本才能结构 低版本报错 低版本直接引入

关于node koa2和express框架搭建swagger_API_10

关于node koa2和express框架搭建swagger_json_11

swagger设置端口一定要与项目端口保持一致

简洁版具体配置:一、 express-swagger-generator 配置

cnpm install  express-swagger-generator
关于node koa2和express框架搭建swagger_API_12
const expressSwagger = require('express-swagger-generator')(app);
const options = {
  swaggerDefinition: {
    info: {
      description: '管理平台',
      title: 'Swagger',
      version: '1.0.0',
    },
    host: 'localhost:3002',
    basePath: '/',//请求路径头
    produces: [
      "application/json",
      "application/xml"
    ],
    schemes: ['http', 'https'],
    securityDefinitions: {
      JWT: {
        type: 'apiKey',
        in: 'header',
        name: 'Authorization',
        description: "",
      }
    }
  },
  route: {
    url: '/doc',
    docs: '/swagger.json' 
  },
  basedir: __dirname, 
  files: ['./routes/*.js'] 
};
expressSwagger(options);
关于node koa2和express框架搭建swagger_json_13
/**
 * @typedef UserJSON
 * @property {string} username.required  - 请输入用户名 - eg: 1
 * @property {string} password.required - 请输入密码 - eg: 1
 */
/**
 * @typedef Error
 * @property {string} code.required
 */


/**
 * 用户登陆
 * @route POST /users/login   
 * @summary 登陆   
 * @group user - 用户相关API
 * @param {UserJSON.model} body.body.required - username&password
 * @returns {object} 200 - 成功
 * @returns {Error}  default - Unexpected error
 */

简洁版具体配置:二、koa2-swagger-ui 配置

npm install koa2-swagger-ui  
npm install swagger-jsdoc

新建文件swagger.js 位置根据自己放

关于node koa2和express框架搭建swagger_Node.js_14
const router = require('koa-router')(); // 引入路由函数
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerDefinition = {
  info: {
    description: '关于API文档',
    version: '1.0.0',
    title: 'Koa2_server Swagger',

  },
  host: 'localhost:4000',
  basePath: '/', // Base path (optional), host/basePath
  schemes: ['http', 'https'],
  securityDefinitions: {
    server_auth: {
      type: 'oauth2',
      description: '登录账号密码鉴权',
      tokenUrl: 'http://localhost:4000/image/oauth',
      flow: 'password',
      scopes: {
        token: 'modify pets in your account'
      }
    },
  }
};
const options = {
  swaggerDefinition,
  // 写有注解的router的存放地址(当你新增swagger时文档里没显示出来的话那么就是这边地址没有加进去)
  apis: ['./routes/*.js'] // routes下所有的js文件
};
const swaggerSpec = swaggerJSDoc(options);
// 通过路由获取生成的注解文件
router.get('/swagger.json', async ctx => {
  ctx.set('Content-Type', 'application/json');
  ctx.body = swaggerSpec;
});

module.exports = router;
// 将页面暴露出去

appjs里引入上面js文件,如果报问题一的错误 把这引用地址替换

关于node koa2和express框架搭建swagger_json_15

关于node koa2和express框架搭建swagger_静态资源_16
const swagger = require('./config/swagger') 
const { koaSwagger } = require('./public/swagger-ui')//这个地址是出现问题一后 静态文件放的位置
app.use(swagger.routes(), swagger.allowedMethods())
app.use(
  koaSwagger({
    routePrefix: '/swagger', // 这里配置swagger的访问路径
    swaggerOptions: {
      url: '/swagger.json', // 这里配置swagger的文档配置URL,也就是说,我们展示的API都是通过这个接口生成的。
    },
  }),
);

再次申明:如需要更详细的配置网上科普帖可以移步 本文主要解决遇到的问题

纯手写不喜勿喷,纯为了避坑,如果对你帮助麻烦点个赞,不明白的地方留言共同学习


About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK