koa初体验———swagger使用

学习完koa框架和mysql，写了一个小demo，选课管理系统，其中包含权限验证，登录注册，用户管理和选课管理。写这个项目目的一方面是为了自己练手，另一方面是为了我们在学习新技术的时候能够有接口供我们使用去测试自己的学习成果。不过更多的是为了大一的考核以及以后大一交互的考核(如果他们觉得我写的好的话)，既然更多的是为了让别人用，那么就作为一个后端的身份去写接口，果然不会写接口的前端不是一个好学长。一般和后端交互的方式是使用swagger页面，所以我也就配置了swagger页面，好让他们更加方便的和后端交互，配置swagger文档遇到的问题我就来分享一下，也是记录我这次小demo吧。

swagger安装

koa2-swagger-ui是生成视图的工具
swagger-jsdoc是识别文档注释生成json的，我们的swagger文件就是根据生成的json文件生成的

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

swagger配置

新建swagger.js文件

const router = require("@koa/router")(); //引入路由函数
const swaggerJSDoc = require("swagger-jsdoc");
const path = require("path");
const swaggerDefinition = {
  info: {
    title: "选课系统",
    version: "1.0.0",
    description: "API",
  },
  host: "127.0.0.1:8000",//设置访问路径，之后文档中的访问接口都是以这个开头，如果访问不到的话可以看看路径拼接的对不对
  basePath: "/",
  //授权（自动传递token）
  securityDefinitions: {
    token: {
      type: "apiKey",
      name: "token",
      in: "header",
    },
  },
};
const options = {
  swaggerDefinition,
  apis: [path.join(__dirname, "./router/*.js")], // 写有注解的router的存放地址，通过读取路由文件的注释生成json文档
};
const swaggerSpec = swaggerJSDoc(options);
// 访问/swagger.json返回生成的json
router.get("/swagger.json", async function (ctx) {
  ctx.set("Content-Type", "application/json");
  ctx.body = swaggerSpec;
});
module.exports = router;

使用swagger.js配置

const { koaSwagger } = require("koa2-swagger-ui");
const swagger = require("../swagger");//存放swagger.js的地方
app.use(swagger.routes(), swagger.allowedMethods());
app.use(
  koaSwagger({
    routePrefix: "/swagger", // 接口文档访问地址
    swaggerOptions: {
      url: "/swagger.json",//生成json的访问路径
    },
  })
);

swagger注释

swagger是根据注释生成的文档，那就要求我们写注释要符合规范
以下是swagger文档的post和get注释
post请求

/**
 * @swagger
 * /users/register: #接口访问路径(拼接上之前swagger.js中的host蛇者)
 *   post: #请求方式
 *     summary: 注册  #接口信息
 *     description: 用户注册 #接口描述
 *     tags: [用户] #接口分组
 *     produces:
 *       - application/x-www-form-urlencoded
 *     parameters: #传递参数
 *       - name: email #参数名字
 *         description: 邮箱 #参数信息
 *         in: formData #参数存放位置formData是存放到请求体中
 *         required: true #是否是必传参数
 *         type: string #参数类型
 *       - name: code
 *         description: 验证码
 *         type: string
 *         in: formData
 *         required: true
 *       - name: password
 *         description: 密码
 *         in: formData
 *         required: true
 *         type: string
 *     responses: #返回结果
 *       200:
 *         description: 成功
 */

get请求

/**
 * @swagger
 * /users/login:
 *   get:
 *     summary: 登录
 *     description: 登录
 *     tags: [用户]
 *     parameters:
 *       - name: email
 *         in: query #参数存放位置。query是存放到请求头里边
 *         required: true
 *         description: 邮箱
 *         type: string
 *       - name: password
 *         in: query
 *         required: true
 *         description: 密码
 *         type: string
 *     responses:
 *       200:
 *         description: 成功
 */

另外如果接口需要传递token的的时候需要添加额外的设置

 *     security:
 *       - token: {}
 *       - server_auth:
 *         - token

以上就是我的swagger配置，以及使用swagger文档的配置过程，之后也需要根据接口的使用情况，来继续完善接口。最后稍微感慨一下吧，写了几天后端越来越感觉自己选前是对的也感谢当时组长给我的建议吧，相对于后端，我确实更喜欢也更适合前端。