关于node koa2和express框架搭建swagger

奋斗吧

擅长邻域：未填写

标签：关于node koa2和express框架搭建swagger 博客 51CTO博客

2023-07-27 18:24:12 123浏览

关于node koa2和express框架搭建swagger，主要分为express和koa2两个框架由于node作为后端得有一份接了

主要分为express和koa2两个框架

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

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

问题一：

关于node koa2和express框架搭建swagger_静态资源

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_静态资源_03

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

koa2

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

express

关于node koa2和express框架搭建swagger_静态资源_05

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

关于node koa2和express框架搭建swagger_API_06

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

关于node koa2和express框架搭建swagger_API_07

koa2 在app引入public的位置

关于node koa2和express框架搭建swagger_json_08

问题二：

关于node koa2和express框架搭建swagger_API_09

koaSwagger is not a function

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

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

关于node koa2和express框架搭建swagger_静态资源_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_Node.js_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都是通过这个接口生成的。
    },
  }),
);