node-使用swagger快速產生API文件

00 緒論

swagger可提供自動化的互動式API文件於網頁上，使相關人員(ex:QA)輕鬆在上面進行測試&查看API的相關參數&路徑。

01 環境建置

加入到Node專案
- 安裝相関套件: $ npm install swagger-autogen swagger-jsdoc swagger-ui-express --save
請手動或使用swagger-autogen來建立swagger.json等檔案

在負責express路由中加入如下程式碼

var swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./config/swagger.json');
...
express.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); //API Docs

打開http://[IP Address]:[Port]/docs來檢視生成結果

02 手動生成文件

請手動建立供給swagger呈現的json檔案: ./config/swagger.json

{
   "openapi": "3.0.0",
   "info": {
      "title": "User API",
      "description": "Simple RESTful API in Node.js with TypeScript",
      "version": "0.0.1"
    },
   "servers": [
      {
        "url": "http://localhost:3000/api",
        "description": "Local server"
      }
   ],
 }

03 把寫好的API功能自動轉成文件

建立自動建立的程式: ./swaggerAutoGen.js

  const swaggerAutogen = require("swagger-autogen")();

  /*需加入定義的API路由規則*/
  const file1="./rules/crawler.js";
  const file2="./rules/sensor.js";
  const file3="./rules/test.js";
  const file4="./rules/users.js";
  const file5="./rules/switch.js";
  const file6="./rules/customValue.js";
  const file7="./rules/mqttPub.js";

 /*文件內部的相關說明*/
 const doc = {
     info: {
     "version": "1.0.5",
     "title": "REST API Test Docs",
     "description": "該文件可提供在該專案中所需提供的功能"
     },
     host: 'localhost:3095',
     basePath: "/",
     schemes: [
       "http"
     ],
 };

 /*輸出對應文件*/
 const endpointsFiles = [file1,file2,file3,file4,file5,file6,file7];
 const outputFile = "./modules/config/swagger.json"; // 輸出的生成結果
 swaggerAutogen(outputFile, endpointsFiles,doc);

加入指定啟動的指令到package.json的scrpits

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "start": "node --max-semi-space-size=128 index.js",
  "swagger-autogen": "node ./tools/swagger.js"
 },

自動生成: $ npm run swagger-autogen

node-使用swagger快速產生API文件

00 緒論

01 環境建置

02 手動生成文件

03 把寫好的API功能自動轉成文件

REF