[記錄五]Vue+node+koa2+mysql+nginx+redis，全棧開發小程式和管理者管理系統項目——使用swagger自動生成接口文檔

因為我們是異地對接接口文檔，為此有對接文檔是非常必要的，經過對比我選用swagger，但是node使用swagger有很多坑（細節）需要注意，我花費了兩天時間才将文檔展現出來，尤其是對注釋部分需要嚴格按照格式去寫。

我這裡選用swagger-jsdoc和koa2-swagger-ui去實作。

首先我們在routes檔案夾中另起一個檔案swagger.js，為什麼在routes檔案下呢？因為在給到别人看文檔的時候你是打開127.0.0.1:300/swaggger這樣的網址的，是以它相當于node的其中一個路由。

下載下傳依賴

npm install swagger-jsdoc koa2-swagger-ui
           

或

yarn add swagger-jsdoc koa2-swagger-ui
           

版本

配置文檔

//swagger.js
const router = require('koa-router')()
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerDefinition = {
  info: {
    title: '你的文檔标題',
    version: '1.0.0',
    description: '你的文檔說明'
  },
  securityDefinitions: {
    ApiKeyAuth: {
      type: 'apiKey', // 類型
      in: 'header', // 位置
      name: 'token' // 參數
    }
  },
  host: '127.0.0.1:300',//需要跟你node伺服器位址一樣
  basePath: '/' // Base path (optional)
};
const options = {
  swaggerDefinition,
  apis: ['./routes/*.js'] // 寫有注解的router的存放位址
};
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檔案引入路由

//app.js
const koaSwagger = require('koa2-swagger-ui')

//swagger配置
app.use(//注意這裡需要看koa2-swagger-ui的版本 不然會報koaSwagger不是一個函數等錯誤
  koaSwagger({
    routePrefix: '/swagger', // host at /swagger instead of default /docs
    swaggerOptions: {
      url: '/swagger.json' // example path to json
    }
  })
)

           

此時頁面是這樣的：

接口注釋

要想接口的路徑和參數等資訊出現在127.0.0.1:300/swagger頁面上，需要在接口那協商注釋；

swagger的注釋是以@swagger開頭的，友善swagger識别：下面以管理者接口為例

//admin.js
// #region 
// #region可以将注釋代碼收縮
/**
 * @swagger
 * /admin/userLogin:
 *   post:
 *     summary: 管理者登入
 *     description: 管理者登入
 *     tags:
 *       - 管理者子產品
 *     parameters:
 *       - name: name
 *         in: query
 *         required: true
 *         description: 賬号
 *         type: string
 *       - name: password
 *         in: query
 *         required: true
 *         description: 密碼
 *         type: string
 *     responses:
 *       200:
 *         description: 成功擷取
 *         schema:
 *           type: 'object'
 *           properties:
 *             code:
 *               type: 'number'
 *             data:
 *               type: 'object'
 *               description: 傳回資料
 *             message:
 *               type: 'string'
 *               description: 消息提示
 */
// #endregion

           

這樣一個比較完整的接口文檔就出來了。頁面上也會出現如下：

這樣就可以将自己的接口文檔輸出到頁面上了。下篇将介紹如何讓遠在他方的小夥伴調用本地的服務。

上一篇：token控制接口權限

下一篇：服務端圖檔上傳和下載下傳