簡介 - 安裝 - 設定(在 Node.js 中開發)

介紹:

Swagger 是一組描述 REST API 的格式的規則/規範。它為程式碼生成器和編輯器等正式規範提供了強大且積極開發的工具生態系統。Swagger 的最佳部分是將方法,引數和模型的文件緊密整合到伺服器程式碼中,從而使 API 始終保持同步。這是一個連結,簡要概述了什麼是 swagger:入門。

寫作規格:

規範可以用 JSON 或 YAML 編寫。因此我們相應地製作了 swagger.json 或 swagger.yaml 檔案。線上編輯器可用於建立檔案。這是一個描述規範語法的連結: http//swagger.io/specification/

使用招搖的方法:

  1. API 優先方法(自上而下方法): 使用 swagger 編輯器→編寫 swagger 定義→使用 swagger-codegen 和 swagger-ui 生成 API
  2. 服務優先方法(自下而上方法): 使用 swagger 註釋開發 JAX-RS 資源類→使用 swagger-core 自動生成 swagger 定義→使用 swagger-codegen 和 swagger-ui 生成客戶端 API 和文件。以上可以在 swagger maven 外掛期間的 maven 構建期間完成。

安裝和設定

在本節中,我們將安裝 swagger,設定 swagger UI 並使用它生成伺服器端和客戶端 SDK。要使用 Node 包管理器安裝 swagger,請執行以下命令:

npm install -g swagger

使用’-g’標誌將確保模組全域性安裝。接下來,我們將使用以下命令建立專案:

swagger project create <project-name>

這將要求使用者選擇用於開發 REST API 的框架。Express 可以選擇相同的。這將建立專案目錄,其中包含以下各項以及每個專案中的 README.md 檔案:

  • API /
    • 控制器/
    • 助手/
    • 嘲笑/
    • 昂首闊步/
  • 配置/
  • 測試/
    • API /
      • 控制器/
      • 助手
  • app.js
  • package.json

伺服器現在基本就緒,可以使用此命令在專案根目錄中執行:

swagger project start

如果主機伺服器設定為 localhost 且未在 app.js 檔案中修改埠號,則伺服器將在以下位置啟動:http://localhost:10010 現在,可以使用 swagger UI 進一步開發 REST API。這可以通過以下方式在新終端中啟動:

swagger project edit

這將在隨機生成的埠上的瀏覽器選項卡中開啟 swagger 編輯器。可以看到示例 hello GET 請求已存在於 swagger.yaml 檔案中。對此檔案的任何進一步更改都將導致伺服器自行重新啟動。

在 paths 部分中,x-swagger-router-controller 使用的值應該是 controllers 資料夾中的 javascript 檔名。作為示例,hello_world.js 應該出現在 controllers 目錄中。此外,operationId 引數的值表示上述 javascript 檔案中的函式名稱。這是應該編寫業務邏輯的地方。因此,我們的 swagger 設定已完成,可用於進一步開發我們的 API。