目錄
5、如何在新版中header裏使用Authorization參數傳遞token
最近學習使用Node構建後臺接口服務，想着使用swagger-ui生成接口調試文檔，查閱了網上相關資料，安裝過程或者使用過程都寫的不是太詳細，對於新手特別是剛上手後臺編程的新手有點不友好，所以我歸納一下我使用過程中涉及的一些方法。
1、安裝
本文章中使用的是swagger-jsdoc和swagger-ui-express兩個結合的形式進行生成swagger-ui接口文檔。所以先安裝一下這兩個模塊。
npm install --save-dev swagger-jsdoc
npm install --save-dev [email protected]
其中需要注意swagger-ui-express建議使用2.0.8版本，雖然這個模塊的版本最新是V4.0.x。因爲博主在使用過程中發現，大於2.0.8版本以上的版本，使用post發起請求是，body裏的數據一直無法傳過去，content-length也一直爲0，而且在自定義header的時候也出現一些問題。樓主後面去GitHub上查了一下issues【點擊跳轉】，按照裏面提出的解決方案我排查了，樓主的代碼是沒問題的，還是無法解決。最後把swagger-ui-express降級到2.0.8纔可以正常使用。所以這裏建議使用這個版本，當然你如果使用最新版本沒問題的話也是可以的。
2、配置
配置swagger基本信息，以及指明接口文件存放的位置
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
const path = require('path');
const config = require('../config/default');
const options = {
definition: {
// swagger 採用的 openapi 版本 不用改
openapi: '3.0.3',
// swagger 頁面基本信息 自由發揮
info: {
title: '後臺管理系統接口',
version: '創建時間：2020年3月27日',
}
},
apis: [ path.join(__dirname, '../router/*.js') ]//這裏指明接口路由存放的文件夾。樓主放在根路徑的router下
}
const swaggerSpec = swaggerJSDoc(options)
module.exports = (app) => {
if(config.ENV === 'Dev'){
// 開放 swagger 相關接口，
app.get('/swagger.json', function(req, res) {
res.setHeader('Content-Type', 'application/json');
res.send(swaggerSpec);
});
// 使用 swaggerSpec 生成 swagger 文檔頁面，並開放在指定路由
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
}
}
3、編寫註釋
按照規範編寫接口註釋，具體規範可以查看這個網站【點擊跳轉】。這裏需要特別注意的是：注意縮減和層次。否則構建出來會有問題。
// 這裏給出樓主項目裏的註釋代碼
// 定義參數
/**
* @swagger
* definition:
* noticeAddParams:
* description: 通知添加參數
* properties:
* title:
* type: string
* content:
* type: string
* endTime:
* type: string
*/
// 定義接口
/**
* @swagger
* /admin/notice/add:
* post:
* tags:
* - 管理員
* description: 通知添加
* consumes:
* - application/json
* - application/xml
* produces:
* - application/json
* - application/xml
* parameters:
* - name: Authorization
* in: header
* required: false
* - name: body
* in: body
* schema:
* $ref: '#/definitions/noticeAddParams'
* responses:
* 200:
* description: 發佈成功
* 402:
* description: 信息填寫不全
* 403:
* description: 參數類型錯誤
*
*/
4、啓動。
啓動node。訪問IP:端口/api-docs。就可以看到自己寫的接口了，也可以進行相關調試。
效果如下：
----------------------------------------------------分割線2020年4月27日14:39:18-------------------------------------------------------------
5、解決新版無法傳輸參數問題
今天有人回覆了我在GitHub上發佈的issues，傳送門。swagger-ui-express大於2.0.8，需要使用openapi3.x規範去編寫註釋，小於2.0.8可以使用openapi2.x版本。3.x版本不兼容2.x。原因在於3.x中使用requestBody作爲數據傳輸的主體，而2.x中使用的是paramters參數。下面給出新版註解：
/**
* @swagger
* /user/login:
* post:
* tags:
* - 用戶
* description: 登錄系統
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/definitions/loginInfo'
* responses:
* 200:
* description: 登錄成功，返回token和用戶信息
*
*/
給出舊版註釋。
/**
* @swagger
* /user/login:
* post:
* tags:
* - 用戶
* description: 登錄系統
* consumes:
* - application/json
* - application/xml
* produces:
* - application/json
* - application/xml
* parameters:
* - name: body
* in: body
* required: true
* schema:
* $ref: "#/definitions/loginInfo"
* responses:
* 200:
* description: 登錄成功，返回token和用戶信息
*
*/
參照上述兩個代碼段，可以發現，新版的body需要放在requestBody裏，而不是放在parameters。requestBody還有很多用法，大家可以參考傳送門裏的那個地址查看。
5、如何在新版中header裏使用Authorization參數傳遞token
在openapi3.x規範中，Authorization這個參數是被OpenAPI佔用的，如果你使用該參數作爲請求頭，你會發現你觸發請求的時候，Authorization參數並不會被攜帶在header中，如果不用這個參數就可以攜帶。那我如果一定要使用這個參數作爲token的攜帶參數怎麼辦？
先給出issues上的答案。傳送門1、傳送門2。也許你會看的雲裏霧裏的，下面我給出我的解決不走。
1）、首先使用components註解聲明全局的securitySchemes。具體參數在傳送門2中有詳細解釋。
/**
* @swagger
* components:
* securitySchemes:
* ApiKeyAuth: // 名稱
* type: apiKey // 類型
* in: header // 位置
* name: Authorization // 參數
*/
2）、去除原先parameters中header的聲明。如果只聲明Authorization這個參數的話，就把聲明去掉，如果還有其他的參數，那就僅去掉Authorization。
3）、引用這些安全聲明。你可以全局引用也可以在API註解中引用。推薦使用後者，可以按照自己的需求自行控制。
/**
* @swagger
* /user/login:
* post:
* tags:
* - 用戶
* description: 登錄系統
* security:
* - ApiKeyAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/definitions/loginInfo'
* responses:
* 200:
* description: 登錄成功，返回token和用戶信息
*
*/
4）、聲明完之後，運行項目。你會發現，添加過security的api後面有跟着一個鎖，且在文檔右上方也出現了一個按鈕。
5）、點擊右上方按鈕或者api後面的鎖，他會彈出一個框要求你輸入Authorization值。按照提示輸入後，點擊確認，鎖圖表從開狀態變成閉合狀態，這時候你在觸發你的api請求，你會發現，swagger自己加上了剛纔你輸入的Authorization值。
從上圖你可以看到，在parameters中，我並沒有添加Authorization這個header字段，而是交給OAS3內置的安全認證去處理。當然你如果不用這個參數，那就非常簡單了，處理如下。
/**
* @swagger
* /admin/notice/add:
* post:
* tags:
* - 管理員
* description: 通知添加
* parameters:
* - in: header
* name: x-http-token
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/definitions/noticeAddParams'
* responses:
* 200:
* description: 獲取成功
*
*/
