NSwag 與 ASP.NET Core 使用者入門

作者:Christoph NienaberRico SuterDave 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 套件] 對話方塊中:

    • 方案總管 > 管理 NuGet 封裝 的專案上按一下滑鼠右鍵
    • 將 [套件來源] 設定為 "nuget.org"
    • 在搜尋方塊中輸入 "NSwag.AspNetCore"
    • 從 [瀏覽] 索引標籤中選取 "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 來產生程式碼

  • 依照 NSwagStudio GitHub 存放庫 (英文) 的指示來安裝 NSwagStudio。 在 [NSwag 發行] 頁面上,您可以下載不需要安裝和系統管理員許可權即可啟動的 xcopy 版本。

  • 啟動 NSwagStudio,然後在 [Swagger Specification URL] (Swagger 規格 URL) 文字方塊中輸入 swagger.json 檔案 URL。 例如: http://localhost:44354/swagger/v1/swagger.json

  • 按一下 [Create local Copy] (建立本機複本) 按鈕,以產生 Swagger 規格的 JSON 表示法。

    建立 Swagger 規格的本機複本

  • 在 [ 輸出 ] 區域中,按一下 [ 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 註解,請執行下列步驟:

  • 以滑鼠右鍵按一下 [方案總管] 中的專案,然後選取 [編輯 <專案名稱>.csproj]。
  • 將醒目提示的程式碼行手動新增至 .csproj 檔案:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • 以滑鼠右鍵按一下方案總管中的專案,然後選取 [屬性]
  • 核取 [組建] 索引標籤之 [輸出] 區段底下的 [ XML 檔 檔案] 方塊

資料註解

由於 NSwag 會使用反映,而針對 Web API 動作建議使用的傳回型別是 IActionResult,因此它無法推斷您動作的執行內容和傳回內容。

請考慮下列範例:

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

上述動作會傳回 IActionResult,但在動作內部則會傳回 CreatedAtRouteBadRequest。 請使用資料註解來告知用戶端已知此動作要傳回哪些 HTTP 狀態碼。 以下列屬性標示動作:

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

由於 NSwag 會使用反映,而 web API 動作的建議傳回型別是 <T> ActionResult,因此它只能推斷所定義的傳回型別 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 7231 規格