因為我們是異地對接介面檔案，為此有對接檔案是非常必要的，經過對比我選用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控制介面權限
下一篇：外網穿透（待寫…）
轉載請註明出處，本文鏈接：https://www.uj5u.com/ruanti/136086.html
標籤：其他
下一篇：周末說說二叉樹之重構