在開發專案前端的過程中，使用 Swagger 讓我省了不少事，提升跟後端溝通的效率，大大減少了溝通成本，今天，要為各位做個簡單的 Swagger 介紹，以及如何在 .net 5.0 中建立 Swagger 服務。

什麼是 Swagger？

簡言之， Swagger 是一套可以幫助開發者與使用者管理 API 的工具。

Swagger 的好處?

  • Swagger 所產生的 API 文件，讓開發者可以知道有哪些 API 可以介接。
  • 可以讓開發者知道，API 需要給那些參數，以及需要使用哪種請求方法（request methods），GET、POST、PUT、DELETE。
  • 隨著專案規模愈大，前後端需要傳遞的資料規格也更複雜，可以幫助前後端一起制定需要傳遞的資料規格。
  • 工程師通常都不喜歡寫文件，可以藉由 Swagger 讓工程師少寫文件。
  • 作為 API 的測試工具，當前端打 API 失敗或是回傳預期外的資料，都可以及時跟後端溝通。

建立 Swagger

  1. 從建立一個新專案開始

  2. 專案類型

  3. 設定專案名稱 與 位置

  4. Framework 設定 .NET 5.0；打開 HTTPS；勾選「啟用 OpenAPI 支援」的話，專案會自動建立 Swagger 服務，我們這次用手動建立，取消勾選。

  5. 專案建立成後，開啟「套件管理員設定」

  6. 在套件來源中，查看是否有關於 NuGet 的套件來源，若無，按新增。

  7. 將名稱改為：NuGet Package source (可自訂)
    來源改為：https://api.nuget.org/v3/index.json

  8. 將套件來源改為：Nuget Package source
    並搜尋：Swashbuckle.AspNetCore
    安裝

  9. 安裝完成

關於 Swashbuckle.AspNetCore

是一套用來文件化 .NET APIs 的 Swagger 工具。
主要有 3 個元件：

  • Swashbuckle.AspNetCore.SwaggerGen
    檢視 API 程式碼，並產生 Swagger Document 物件。
  • Swashbuckle.AspNetCore.Swagger
    可將 Swagger Document 物件公開為 JSON 端點。
  • Swashbuckle.AspNetCore.SwaggerUI
    產生 API 文件，讓使用者在網頁測試 API。

  1. 將 Swashbuckle.AspNetCore.SwaggerGen 加入 Startup.ConfigureServices應用程式服務之中

    1
    services.AddSwaggerGen();

  2. 將 Swashbuckle.AspNetCore.Swagger 加入 Startup.Configure

    1
    app.UseSwagger();

  3. 將 Swashbuckle.AspNetCore.SwaggerUI 加入 Startup.Configure

    1
    2
    3
    4
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "weatherForecast v1");
    });


    SwaggerEndpoint 方法的 - 第一個參數
    為 Swagger Document 物件的 Endpoint 位置，v1 是 Swagger Document 物件的預設名稱，所以 /swagger/v1/swagger.json 是預設路由位置。
    v1 名稱是可以修改的，之後會補充。 - 第二個參數
    會顯示在 Swagger UI 右上角，之後若有多個不同類別的 API，可以由此切換。

  4. 將 launchSettings.json 內，專案的 launchUrl 改成 Swagger

  5. 選取專案，啟動 Swagger 服務 (Ctrl + F5)

  6. Swagger UI 預設的網址路由為 https://localhost:5001/swagger
    顯示目前唯一的預設 API WeatherForecast

  7. Swagger 所產生的 Swagger Document 物件 URL：https://localhost:5001/swagger/v1/swagger.json

以上就是建立 Swagger 的流程，關於 Swagger UI 顯示的資訊，說明與修改，將另開篇幅討稐。

參考