swagger開心的swagger


備註

本節概述了什麼是swagger,以及開發人員可能想要使用它的原因。

它還應該提到招搖中的任何大型主題,並鏈接到相關主題。由於swagger文檔是新的,您可能需要創建這些相關主題的初始版本。

簡介 - 安裝 - 設置(在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 文件中修改端口號,則服務器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。