一、版本說明
"vue": "^2.6.10",
"axios": "^0.19.0",
"@vue/cli-plugin-babel": "^4.0.0",
"@vue/cli-plugin-router": "^4.0.0",
"@vue/cli-plugin-typescript": "^4.0.0",
"@vue/cli-plugin-vuex": "^4.0.0",
"@vue/cli-service": "^4.0.0",
"vue-loader": "^15.7.1",
"vue-router": "^3.1.3",
"faker": "^4.1.0",
"typescript": "~3.5.3"
"node": 10.13.0, // cmd命令窗輸入：node -v
"npm": 6.10.3, // cmd命令窗輸入：npm -v
"typescript": 3.7.4 // cmd命令窗輸入：tsc -v
"swagger": 0.7.5 // cmd命令窗輸入：swagger -V
二、此時已經搭建好 Vue 項目（可以是 Vue + JavaScript，也可是 Vue + TypeScript（本項目選擇此方式構建）），需要單獨創建 swagger 項目，即搭建服務器，用於生成接口
2.1、用 Swagger 搭建服務器 （ 'API'框架選擇的 Express ）
2.2、 全局安裝 swagger（前提先安裝 nodejs、npm） 
npm install -g swagger
2.3、創建一個工作目錄，在工作目錄下創建服務器項目（本項目直接在 Vue 項目根目錄下創建的，工作目錄看自己心情哈）
swagger project create mock-server // 創建項目名爲 ‘mock-server’
選擇 `API` 框架： express
cd mock-server // 進入目錄 ‘mock-server’
swagger project start // 啓動 server（swagger 項目），在 ‘mock-server’ 目錄下
搭建後的項目目錄如下：
2.4、啓動時，【出現錯誤】 cannot find module 'swagger-express-mw'
2.5、【解決辦法】 
在 Vue 項目下（因爲本次項目在 Vue根目錄下，也可以直接在 mock-server 目錄下），安裝 `swagger-express-mw`
npm install swagger-express-mw --save-dev // 安裝中間件 `swagger-express-mw`
cd mock-server // 切換到新創建的目錄
swagger project start // 啓動 swagger 項目
然後輸入網址 http://127.0.0.1:10010/hello?name=Scott ，瀏覽器成功返回信息
2.6、現在打開本地 swagger 編輯頁面（也可以用 swagger 在線編輯），在創建的項目目錄（‘mock-server’ ）中，打開另外一個 cmd 窗口，輸入以下指令啓動 Swagger Editor：
swagger project edit // 啓動 edit，在 ‘mock-server’ 目錄下
此時有一個測試接口 '/hello'
三、並添加 Controller 以返回自定義數據， 安裝 Faker.js（ 添加自定義接口 ）
3.1、需要添加一個 controller 來控制 router 的返回，首先安裝中間件 Faker.js（用於生成隨機數據，避免手動添加數據）， Faker.js 文檔參考這裏
npm install faker --save-dev // 在 Vue 所在項目或 ‘mock-server’目錄下 安裝Faker.js
3.2、修改 yaml 文件：在 yaml 文件中添加 controller 的文件名 user 和 方法名 getUser
- 其中 x-swagger-router-controller 會促使 swagger 去 api/controller 目錄下尋找對應的 js 文件
- operationId 則是每一個請求方式對應的 controller 中的方法
![]()
swagger.yaml 文件添加內容如下
新建文件 api\controllers\user.js ， 即提供的接口文件，文件內容如下
啓動 server 和 editor
swagger project start // ‘mock-server’ 目錄下
swagger project edit // ‘mock-server’ 目錄下
打開命令窗口 swagger project edit 所顯示的地址，默認自動打開此地址，即 http://127.0.0.1/xxxxx/#!/ ，請求之後顯示如下：
四、以上步驟能實現基本就可以了，因爲默認生成的啓動文件是 app.js ，想要讓 swagger 識別 TypeScript 類型文件，即 app.ts、table.ts等
4.1、首先確認安裝了 swagger、faker， 然後全局安裝 ts-node、typescript、cross-env（解決 Windows 兼容性問題）
npm install -g swagger // 全局安裝 'swagger'
npm install faker --save-dev // 安裝中間件 'faker'
npm install -g ts-node // 全局安裝 'ts-node'
npm install -g typescript // 全局安裝 'typescript'
npm install -g cross-env --save-dev // 安裝中間件 'cross-env'
4.2、在 server 項目下，即目錄‘mock-server’下，初始化 TypeScript，生成 tsconfig.json 文件
tsc init // 生成 tsconfig.json 文件，‘mock-server’ 目錄下
4.3、然後修改 tsconfig.json 文件內容如下
{
"compilerOptions": {
"target": "es5",
"module": "commonjs",
"strict": true,
"jsx": "preserve",
"importHelpers": true,
"moduleResolution": "node",
"experimentalDecorators": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"forceConsistentCasingInFileNames": true,
"sourceMap": true,
"baseUrl": ".",
"types": [
"node",
"webpack-env"
]
},
"include": [
"**/*.ts",
"**/*.tsx"
],
"exclude": [
"node_modules"
]
}
4.4、修改文件 app.js 爲 app.ts，然後直接命令窗 'swagger project start' 時，會報錯說找不到 app.js 文件，查看‘mock-server’目錄下的 package.json 文件，發現需要修改以下兩處
- 將 app.js 替換成 app.ts
- 並且在腳本命令前加上 ‘cross-env’
4.5、【再次報錯】需要修改 app.ts 文件內容，TypeScript 返回的參數需要定義類型
4.6、【成功執行】 
4.7、此時將 controllers\table.js 修改爲 table.ts，用 swagger 請求接口時，會獲取失敗，這時需要安裝中間件 'swagger-tools'
npm install swagger-tools --save // 中間件 'swagger-tools' 可以接受 '*.ts' 的文件，‘mock-server’ 目錄下
swagger.yaml 文件不需要修改
此時 hello_world.js 文件也可以支持，返回內容需要是數組類型
接口 ‘/userLists’ 返回數據如下
五、因爲正常項目，都會返回狀態值(200、401、404、-1 等)，所以修改接口 ‘/userLists’ 返回的內容格式，如需要以下格式：
5.1、修改 swagger.yaml 文件內容，參考這裏 
5.2、修改 tables.ts 邏輯文件
5.3、【成功】請求接口時，控制檯返回的數據如下，到此就算成功啦
總結：
- 1、首先需要單獨建立一個服務器項目，並且需要以 swagger 命令格式去生成項目
- 2、安裝時選擇‘API’框架，此時選的 express，若出現什麼模板找不到時，就安裝試一試，如上述 'swagger-express-mw' 找不到
- 3、'swagger project start '用於啓動 server 項目，'swagger project edit'用於啓動本地 swagger 編輯頁面
- 4、然後根據需求安裝中間件，如隨機數據安裝中間件 Faker.js，需要使用 TypeScript 語法，需要安裝對應中間件和修改相應文件（也得讓 swagger 識別 *.ts 文件）
- 5、接口返回數據格式，需要修改 swagger.yaml 文件，參考這裏
- 6、寫給自己的隨筆，有問題歡迎指出(Θ▽Θ)
