koa API文檔 使用Swagger

公司用了swagger,感覺美觀，至少比我之前用到的apidoc 鏈 接 好太多了。當然，收費的api文檔工具另算。

本文以koa項目爲例

npm install koa2-generator -g
koa2 projectName # koa2 不能koa 版本不一樣

安裝swagger相關依賴

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

# koa2-swagger-ui UI視圖組件  swagger-jsdoc 識別寫的 /***/ 轉 json

根目錄下新建util文件夾 新建swagger.js

const router = require('koa-router')() //引入路由函數
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerDefinition = {
    info: {
        title: '個人網站api藉口',
        version: '1.0.0',
        description: 'API',
    },
    host: 'localhost:3000',
    basePath: '/' // Base path (optional)
};
const options = {
    swaggerDefinition,
    apis: [path.join(__dirname,'../routes/*.js')], // 寫有註解的router的存放地址, 最好path.join()
};
const swaggerSpec = swaggerJSDoc(options)
// 通過路由獲取生成的註解文件
router.get('/swagger.json', async function (ctx) {
    ctx.set('Content-Type', 'application/json');
    ctx.body = swaggerSpec;
})
module.exports = router

app.js

const index = require('./routes/index')
const users = require('./routes/users')
+ const swagger = require('./util/swagger')
+ app.use(swagger.routes(), swagger.allowedMethods())


+ const koaSwagger = require('koa2-swagger-ui')
+ app.use(koaSwagger({
+  routePrefix: '/swagger', // host at /swagger instead of default /docs
+  swaggerOptions: {
+    url: '/swagger.json', // example path to json 其實就是之後swagger-jsdoc生成的文檔地址
+ },
+}))

總體的思路 就是 先生成對應的json數據，再swagger UI配置json 導出

現在 寫api接口 模板

swagger-jsdoc github 地址

在router文件夾下 根據實際業務需求編寫 我整理一份常用的

  // 定義模型 可以公用 schema $ref
  /**
   * @swagger
   * definitions:
   *   Login:
   *     required:
   *       - username
   *       - password
   *     properties:
   *       username:
   *         type: string
   *       password:
   *         type: string
   *       path:
   *         type: string
   */


  //  tags 可以理解成藉口分類  parameters 參數
  /**
   * @swagger
   * /login:
   *   post:
   *     description: 用戶登入
   *     tags: [用戶登入模塊]
   *     produces:
   *       - application/json
   *     parameters:
   *       - name: password
   *         description: 用戶密碼.
   *         in: formData
   *         required: true
   *         type: string
   *       - name: username
   *         description: 用戶名.
   *         in: formData
   *         required: true
   *         type: string
   *     responses:
   *       200:
   *         description: 登入成功
   *         schema:
   *           type: object
   *           $ref: '#/definitions/Login'
   *   
   */

如果你嫌棄這樣會導致你項目臃腫，可以在線生成json文檔，之後直接讀取 地址。但是注意版本，個人後期覺得在線編輯會好很多，再加上openapi: 3.0.0新版本有很多不錯的點，比如支持了requestBody

在線編輯有坑點，你接口是http,如果在線編輯器是https,會請求失敗

收工，完美