NSwag 與 ASP.NET Core 使用者入門

發行項
01/28/2023

作者：Christoph Nienaber、Rico Suter 及 Dave Brock

檢視或下載範例程式碼 \(英文\) (如何下載)

NSwag 提供下列功能：

能夠運用 Swagger UI 和 Swagger 產生器。
彈性的程式碼產生功能。

使用 NSwag 時，您不需要現有的 API—您可以使用包含 Swagger 並產生用戶端實作的協力廠商 API。 NSwag 可讓您加速開發週期，並輕鬆地因應 API 變更進行調整。

註冊 NSwag 中介軟體

註冊 NSwag 中介軟體來：

為實作的 Web API 產生 Swagger 規格。
提供 Swagger UI 以瀏覽並測試 Web API。

若要使用 NSwag ASP.NET Core 中介軟體，請安裝 NSwag.AspNetCore NuGet 套件。此套件包含用以產生並提供 Swagger 規格、Swagger UI (v2 和 v3) 及 ReDoc UI 的中介軟體。

請使用下列其中一種方法來安裝 NSwag NuGet 套件：

從 [套件管理員主控台] 視窗中：
- 移至檢視>其他 Windows>套件管理員主控台
- 流覽至檔案所在的目錄 TodoApi.csproj
- 執行下列命令：
```
Install-Package NSwag.AspNetCore
```
從 [管理 NuGet 套件] 對話方塊中：
- 以滑鼠右鍵按一下方案總管>Manage NuGet 套件中的專案
- 將 [套件來源] 設定為 "nuget.org"
- 在搜尋方塊中輸入 "NSwag.AspNetCore"
- 從 [瀏覽] 索引標籤中選取 "NSwag.AspNetCore" 套件，並按一下 [安裝]

執行以下命令：

dotnet add TodoApi.csproj package NSwag.AspNetCore

新增和設定 Swagger 中介軟體

請執行下列步驟，以在您的 ASP.NET Core 應用程式中新增及設定 Swagger：

在 Startup.ConfigureServices 方法中，註冊所需的 Swagger 服務：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}

在 Startup.Configure 方法中，啟用中介軟體為產生的 Swagger 規格和 SwaggerUI 提供服務：

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseMvc();
}

啟動應用程式。瀏覽至：
- http://localhost:<port>/swagger 以檢視 Swagger UI。
- http://localhost:<port>/swagger/v1/swagger.json 以檢視 Swagger 規格。

程式碼產生

您可以選擇下列其中一個選項來利用 NSwag 的程式碼產生功能：

NSwagStudio：Windows 傳統型應用程式，用於在 C# 或 TypeScript 中產生 API 用戶端程式代碼。
可在您專案內產生程式碼的 NSwag.CodeGeneration.CSharp 或 NSwag.CodeGeneration.TypeScript NuGet 套件。
從命令列使用 NSwag。
NSwag.MSBuild NuGet 套件。
Unchase OpenAPI (Swagger) Connected Service：Visual Studio Connected Service，用於在 C# 或 TypeScript 中產生 API 用戶端程式代碼。也會使用 NSwag 產生用於 OpenAPI 服務的 C# 控制器。

使用 NSwagStudio 來產生程式碼

依照 NSwagStudio GitHub 存放庫 \(英文\) 的指示來安裝 NSwagStudio。在 NSwag 發行頁面上，您可以下載 xcopy 版本，該版本可以在沒有安裝和系統管理員許可權的情況下啟動。
啟動 NSwagStudio，然後在[Swagger 規格 URL] 文字方塊中輸入 swagger.json 檔案 URL。例如： http://localhost:44354/swagger/v1/swagger.json 。
按一下 [ 建立本機複製] 按鈕，以產生 JS Swagger 規格的 ON 標記法。
在 [ 輸出 ] 區域中，按一下 [CSharp 用戶端 ] 核取方塊。視您的專案而定，您也可以選擇 [TypeScript Client] \(TypeScript 用戶端\)或 [CSharp Web API Controller] \(CSharp Web API 控制器\)。如果您選取 [CSharp Web API Controller] \(CSharp Web API 控制器\)，服務規格會重建服務，作為反向產生。
按一下 [Generate Outputs] \(產生輸出\)，以產生 TodoApi.NSwag 專案的完整 C# 用戶端實作。若要查看所產生的用戶端程式碼，請按一下 [CSharp Client] \(CSharp 用戶端\) 索引標籤：

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "https://localhost:44354";
        private System.Net.Http.HttpClient _httpClient;
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
                var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
                return settings;
            });
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set { _baseUrl = value; }
        }

        // code omitted for brevity

提示

C# 用戶端程式代碼是根據 [ 設定 ] 索引標籤中的選取專案產生。修改設定以執行工作，例如預設命名空間重新命名和同步方法產生。

將產生的 C# 程式碼複製到將取用 API 的用戶端專案中檔案。
開始取用 Web API：

 var todoClient = new TodoClient();

// Gets all to-dos from the API
 var allTodos = await todoClient.GetAllAsync();

 // Create a new TodoItem, and save it via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

自訂 API 文件

Swagger 提供選項來記錄物件模型，以簡化 Web API 的取用作業。

API 資訊與描述

在 Startup.ConfigureServices 方法中，傳遞至 AddSwaggerDocument 方法的組態動作會新增作者、授權和描述等資訊：

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.OpenApiLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Swagger UI 會顯示版本資訊：

含有版本資訊的 Swagger UI

XML 註解

若要啟用 XML 註解，請執行下列步驟：

以滑鼠右鍵按一下方案總管中的專案，然後選取 Edit <project_name>.csproj 。
手動將醒目提示的行新增至 .csproj 檔案：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

從 [Solution Pad] 中，按下 [控制項]，然後按一下專案名稱。流覽至[工具>編輯檔案]。
手動將醒目提示的行新增至 .csproj 檔案：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

手動將醒目提示的行新增至 .csproj 檔案：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

資料註解

由於 NSwag 使用反映，且 Web API 動作的建議傳回類型為ActionResult < T >，因此只能推斷所 T 定義的傳回型別。您無法自動推斷其他可能的傳回型別。

請思考一下下列範例：

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

上述動作會傳回 ActionResult<T>。在動作內，它會傳 CreatedAtRoute 回。由於控制器具有 [ApiController] 屬性， BadRequest 因此也可以提供回應。如需詳細資訊，請參閱自動 HTTP 400 回應。請使用資料註解來告知用戶端已知此動作要傳回哪些 HTTP 狀態碼。使用下列屬性標記動作：

[ProducesResponseType(StatusCodes.Status201Created)]     // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

在 ASP.NET Core 2.2 或更新版本中，您可以使用慣例，而不使用 [ProducesResponseType] 來明確地裝飾個別動作。如需詳細資訊，請參閱使用 Web API 慣例。

Swagger 產生器現在可以正確描述此動作，而產生的用戶端會知道呼叫端點時它們所接收的內容。建議使用這些屬性標示所有動作。

如需 API 動作應該傳回之 HTTP 回應的指導方針，請參閱 RFC 9110：HTTP 語意 (第 9.3 節。方法定義) 。

作者：Christoph Nienaber、Rico Suter 及 Dave Brock

檢視或下載範例程式碼 \(英文\) (如何下載)

NSwag 提供下列功能：

能夠運用 Swagger UI 和 Swagger 產生器。
彈性的程式碼產生功能。

註冊 NSwag 中介軟體

註冊 NSwag 中介軟體來：

為實作的 Web API 產生 Swagger 規格。
提供 Swagger UI 以瀏覽並測試 Web API。

若要使用 NSwag ASP.NET Core 中介軟體，請安裝 NSwag.AspNetCore NuGet 套件。此套件包含用以產生並提供 Swagger 規格、Swagger UI (v2 和 v3) 及 ReDoc UI 的中介軟體。

請使用下列其中一種方法來安裝 NSwag NuGet 套件：

從 [套件管理員主控台] 視窗中：
- 移至檢視>其他 Windows>套件管理員主控台
- 流覽至檔案所在的目錄 TodoApi.csproj
- 執行下列命令：
```
Install-Package NSwag.AspNetCore
```
從 [管理 NuGet 套件] 對話方塊中：
- 以滑鼠右鍵按一下方案總管>Manage NuGet 套件中的專案
- 將 [套件來源] 設定為 "nuget.org"
- 在搜尋方塊中輸入 "NSwag.AspNetCore"
- 從 [瀏覽] 索引標籤中選取 "NSwag.AspNetCore" 套件，並按一下 [安裝]

執行以下命令：

dotnet add TodoApi.csproj package NSwag.AspNetCore

新增和設定 Swagger 中介軟體

請執行下列步驟，以在您的 ASP.NET Core 應用程式中新增及設定 Swagger：

在 Startup.ConfigureServices 方法中，註冊所需的 Swagger 服務：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}

在 Startup.Configure 方法中，啟用中介軟體為產生的 Swagger 規格和 SwaggerUI 提供服務：

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseMvc();
}

啟動應用程式。瀏覽至：
- http://localhost:<port>/swagger 以檢視 Swagger UI。
- http://localhost:<port>/swagger/v1/swagger.json 以檢視 Swagger 規格。

程式碼產生

您可以選擇下列其中一個選項來利用 NSwag 的程式碼產生功能：

NSwagStudio：Windows 傳統型應用程式，用於在 C# 或 TypeScript 中產生 API 用戶端程式代碼。
可在您專案內產生程式碼的 NSwag.CodeGeneration.CSharp 或 NSwag.CodeGeneration.TypeScript NuGet 套件。
從命令列使用 NSwag。
NSwag.MSBuild NuGet 套件。
Unchase OpenAPI (Swagger) Connected Service：Visual Studio Connected Service，用於在 C# 或 TypeScript 中產生 API 用戶端程式代碼。也會使用 NSwag 產生用於 OpenAPI 服務的 C# 控制器。

使用 NSwagStudio 來產生程式碼

依照 NSwagStudio GitHub 存放庫 \(英文\) 的指示來安裝 NSwagStudio。在 NSwag 發行頁面上，您可以下載 xcopy 版本，該版本可以在沒有安裝和系統管理員許可權的情況下啟動。
啟動 NSwagStudio，然後在[Swagger 規格 URL] 文字方塊中輸入 swagger.json 檔案 URL。例如： http://localhost:44354/swagger/v1/swagger.json 。
按一下 [ 建立本機複製] 按鈕，以產生 JS Swagger 規格的 ON 標記法。
在 [ 輸出 ] 區域中，按一下 [CSharp 用戶端 ] 核取方塊。視您的專案而定，您也可以選擇 [TypeScript Client] \(TypeScript 用戶端\)或 [CSharp Web API Controller] \(CSharp Web API 控制器\)。如果您選取 [CSharp Web API Controller] \(CSharp Web API 控制器\)，服務規格會重建服務，作為反向產生。
按一下 [Generate Outputs] \(產生輸出\)，以產生 TodoApi.NSwag 專案的完整 C# 用戶端實作。若要查看所產生的用戶端程式碼，請按一下 [CSharp Client] \(CSharp 用戶端\) 索引標籤：

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "https://localhost:44354";
        private System.Net.Http.HttpClient _httpClient;
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
                var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
                return settings;
            });
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set { _baseUrl = value; }
        }

        // code omitted for brevity

提示

C# 用戶端程式代碼是根據 [ 設定 ] 索引標籤中的選取專案產生。修改設定以執行工作，例如預設命名空間重新命名和同步方法產生。

將產生的 C# 程式碼複製到將取用 API 的用戶端專案中檔案。
開始取用 Web API：

 var todoClient = new TodoClient();

// Gets all to-dos from the API
 var allTodos = await todoClient.GetAllAsync();

 // Create a new TodoItem, and save it via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

自訂 API 文件

Swagger 提供選項來記錄物件模型，以簡化 Web API 的取用作業。

API 資訊與描述

在 Startup.ConfigureServices 方法中，傳遞至 AddSwaggerDocument 方法的組態動作會新增作者、授權和描述等資訊：

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.OpenApiLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Swagger UI 會顯示版本資訊：

含有版本資訊的 Swagger UI

XML 註解

若要啟用 XML 註解，請執行下列步驟：

以滑鼠右鍵按一下方案總管中的專案，然後選取 Edit <project_name>.csproj 。
手動將醒目提示的行新增至 .csproj 檔案：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

從 [Solution Pad] 中，按下 [控制項]，然後按一下專案名稱。流覽至[工具>編輯檔案]。
手動將醒目提示的行新增至 .csproj 檔案：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

手動將醒目提示的行新增至 .csproj 檔案：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

資料註解

由於 NSwag 使用反映，且 Web API 動作的建議傳回類型為ActionResult < T >，因此只能推斷所 T 定義的傳回型別。您無法自動推斷其他可能的傳回型別。

請思考一下下列範例：

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

[ProducesResponseType(StatusCodes.Status201Created)]     // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

在 ASP.NET Core 2.2 或更新版本中，您可以使用慣例，而不使用 [ProducesResponseType] 來明確地裝飾個別動作。如需詳細資訊，請參閱使用 Web API 慣例。

Swagger 產生器現在可以正確描述此動作，而產生的用戶端會知道呼叫端點時它們所接收的內容。建議使用這些屬性標示所有動作。

如需 API 動作應該傳回之 HTTP 回應的指導方針，請參閱 RFC 9110：HTTP 語意 (第 9.3 節。方法定義) 。

NSwag 與 ASP.NET Core 使用者入門

註冊 NSwag 中介軟體

新增和設定 Swagger 中介軟體

程式碼產生

使用 NSwagStudio 來產生程式碼

自訂 API 文件

API 資訊與描述

XML 註解

資料註解

註冊 NSwag 中介軟體

新增和設定 Swagger 中介軟體

程式碼產生

使用 NSwagStudio 來產生程式碼

自訂 API 文件

API 資訊與描述

XML 註解

資料註解

其他資源

其他資源