使用 Swagger 工具記錄 ASP.Net Core Web API
API 可發揮絕佳價值，但除非開發人員了解使用方式，否則便不會獲得認可。 開發人員希望能儘快整合 API。 良好的 API 文件可協助開發人員了解 API 的功能與使用方式，讓整合更有效率。
傳統上，描述 API 和其使用方式的所有文件都是以手動方式撰寫而成。 現在我們有一個稱為 OpenAPI 的標準 API 描述規格。 Swagger UI 提供適用於 API 的 OpenAPI 規格實作和測試工具。 Swashbuckle 是開放原始碼套件，可利用 .NET 反映直接從 Web API 控制器自動產生 OpenAPI 描述文件。 Swashbuckle 可以協助您將文件流程自動化，方便小組產生、維護和使用以 OpenAPI 危機處得 API 文件。 您負責描述 API，至於產生豐富的文件，就交給工具。
什麼是 OpenAPI？
OpenAPI 是用來描述 REST API 的規格。 其與語言無關，並可讓您描述整個 API，包含：
- 可用的端點
- 作業參數
- 驗證方法
- 連絡人和其他資訊
您可以使用 YAML 或 JSON 來撰寫 API 規格。 使用 OpenAPI 規格，人類和電腦不需要存取 API 的原始程式碼，就能夠了解其功能。
什麼是 Swagger？
Swagger 是依據 OpenAPI 規格所建置的一組開放原始碼工具。 這些工具可協助您設計、建置和記錄 REST API。 Swagger 使用 API 的 OpenAPI 規格來了解其結構。
例如，Swagger UI 是一種工具，能為使用 OpenAPI 規格定義的 API，在瀏覽器中以視覺化方式呈現 API 文件。 Swagger Codegen 可以採用和 API 相同的 OpenAPI 規格，並產生用戶端 SDK。
是什麼 Swashbuckle？
Swashbuckle 是開放原始碼Swagger 實作，可使用 .NET 反映產生 .NET Core API 的 Swagger 文件。
Swashbuckle 有三個主要元件：
Swashbuckle.AspNetCore.Swagger：此元件是 Swagger 物件模型與中介軟體，可將
SwaggerDocument物件公開為 JSON 端點。Swashbuckle.AspNetCore.SwaggerGen：此程式庫是 Swagger 產生器，可直接從路由、控制器及模型建立
SwaggerDocument物件。 程式庫通常會結合 Swagger 端點中介軟體，以便自動公開 Swagger JSON。Swashbuckle.AspNetCore.SwaggerUI：此套件是 Swagger UI 工具內嵌版本。 它可以解譯 Swagger JSON，建置豐富、可自訂的 Web API 功能描述體驗。 其中包括公用方法的內建測試載入器。
Swashbuckle CLI：安裝之後，這個 .NET 全域工具就能在建置/發佈期間產生 OpenAPI 規格。 在本課程模組結尾提供此工具的下載連結。
因為這些程式庫會新增至您的應用程式，所以可從最新版的 API 產生 API 文件，並以視覺化方式呈現。 它們會建立即時文件，一律會與最新程式碼保持同步。