使用 Swagger/Open API 的 ASP.NET Core Web API 說明頁面ASP.NET Core Web API help pages with Swagger / Open API

作者:Christoph NienaberRico SuterBy Christoph Nienaber and Rico Suter

使用 Web API 時,了解其各種不同的方法對開對發人員來說可能是一項挑戰。When consuming a Web API, understanding its various methods can be challenging for a developer. Swagger (也稱為 Open API) 解決為 Web API 產生有用文件與說明頁面的問題。Swagger, also known as Open API, solves the problem of generating useful documentation and help pages for Web APIs. 它提供如互動式文件、用戶端 SDK 產生作業和 API 發現性等優點。It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

在本文中,展示了 Swashbuckle.AspNetCoreNSwag .NET Swagger 實作:In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:

  • Swashbuckle.AspNetCore 是用來為 ASP.NET Core Web API 產生 Swagger 文件的開放原始碼專案。Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs.

  • NSwag 是用來將 Swagger UIReDoc 整合到 ASP.NET Core Web API 的其他開放原始碼專案。NSwag is another open source project for integrating Swagger UI or ReDoc into ASP.NET Core Web APIs. 它提供方法來為您的 API 產生 C# 和 TypeScript 用戶端程式碼。It offers approaches to generate C# and TypeScript client code for your API.

何謂 Swagger/Open API?What is Swagger / Open API?

Swagger 是用來描述 REST API 的語言無關規格。Swagger is a language-agnostic specification for describing REST APIs. Swagger 專案已捐贈給 OpenAPI Initiative (OpenAPI 方案),目前在該方案中它稱為 Open API。The Swagger project was donated to the OpenAPI Initiative, where it's now referred to as Open API. 這兩個名稱可交替使用;不過,Open API 是慣用名稱。Both names are used interchangeably; however, Open API is preferred. 它可讓電腦和人類都了解服務的功能,而不必直接存取實作 (原始碼、網路存取、文件)。It allows both computers and humans to understand the capabilities of a service without any direct access to the implementation (source code, network access, documentation). 其中一個目標是要將連線未相關聯之服務所需的工作量減到最少。One goal is to minimize the amount of work needed to connect disassociated services. 另一個目標則是減少正確記錄服務所需的時間量。Another goal is to reduce the amount of time needed to accurately document a service.

Swagger 規格 (swagger.json)Swagger specification (swagger.json)

Swagger 流程的核心是 Swagger 規格—根據預設,文件名為 swagger.jsonThe core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. 它是由 Swagger 工具鏈 (或其協力廠商實作) 根據您的服務所產生。It's generated by the Swagger tool chain (or third-party implementations of it) based on your service. 它會描述 API 的功能,以及如何使用 HTTP 來進行存取。It describes the capabilities of your API and how to access it with HTTP. 它可驅動 Swagger UI,並由工具鏈用來啟用探索和產生用戶端程式碼功能。It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. 以下是 Swagger 規格的範例,為求簡單明瞭,其已經過縮減:Here's an example of a Swagger specification, reduced for brevity:

{
   "swagger": "2.0",
   "info": {
       "version": "v1",
       "title": "API V1"
   },
   "basePath": "/",
   "paths": {
       "/api/Todo": {
           "get": {
               "tags": [
                   "Todo"
               ],
               "operationId": "ApiTodoGet",
               "consumes": [],
               "produces": [
                   "text/plain",
                   "application/json",
                   "text/json"
               ],
               "responses": {
                   "200": {
                       "description": "Success",
                       "schema": {
                           "type": "array",
                           "items": {
                               "$ref": "#/definitions/TodoItem"
                           }
                       }
                   }
                }
           },
           "post": {
               ...
           }
       },
       "/api/Todo/{id}": {
           "get": {
               ...
           },
           "put": {
               ...
           },
           "delete": {
               ...
   },
   "definitions": {
       "TodoItem": {
           "type": "object",
            "properties": {
                "id": {
                    "format": "int64",
                    "type": "integer"
                },
                "name": {
                    "type": "string"
                },
                "isComplete": {
                    "default": false,
                    "type": "boolean"
                }
            }
       }
   },
   "securityDefinitions": {}
}

Swagger UISwagger UI

Swagger UI 使用產生的 Swagger 規格提供 Web UI ,以提供服務的相關資訊。Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger specification. Swashbuckle 和 NSwag 都包含內嵌的 Swagger UI 版本,因此它可以使用中介軟體的登錄呼叫裝載在 ASP.NET Core 應用程式中。Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be hosted in your ASP.NET Core app using a middleware registration call. Web UI 顯示如下:The web UI looks like this:

Swagger UI

控制器中的每個公用動作方法都可以從 UI 進行測試。Each public action method in your controllers can be tested from the UI. 按一下方法名稱以展開該區段。Click a method name to expand the section. 新增任何必要的參數,然後按一下 [試試看!]。Add any necessary parameters, and click Try it out!.

範例 Swagger GET 測試

注意

用於螢幕擷取畫面的 Swagger UI 版本為第 2 版。The Swagger UI version used for the screenshots is version 2. 如需第 3 版的範例,請參閱 Petstore 範例For a version 3 example, see Petstore example.

後續步驟Next steps