歡迎光臨
每天分享高質量文章

NSwag 和 ASP.NET Core

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 包,請使用以下方法之一:

 

  • 從“程式包管理器控制台”視窗:

    • 轉到“視圖” > “其他視窗” > “程式包管理器控制台”

    • 導航到包含 TodoApi.csproj 檔案的目錄

    • 請執行以下命令:

      Install-Package NSwag.AspNetCore
      
  • 從“管理 NuGet 程式包”對話框中:

    • 右鍵單擊“解決方案資源管理器” > “管理 NuGet 包”中的專案
    • 將“包源”設置為“nuget.org”
    • 在搜索框中輸入“NSwag.AspNetCore”
    • 從“瀏覽”選項卡中選擇“NSwag.AspNetCore”包,然後單擊“安裝”

 

添加並配置 Swagger 中間件

通過在 Startup 類中執行以下步驟,在 ASP.NET Core 應用中添加和配置 Swagger:

  • 匯入下列命名空間:
using NJsonSchema;
using NSwag.AspNetCore;
  • 在 ConfigureServices 方法中,註冊所需的 Swagger 服務:
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext(opt => 
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}
  • 在 Configure 方法中,啟用中間件為生成的 Swagger 規範和 Swagger UI 提供服務:
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

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

    app.UseMvc();
}
  • 啟動應用。 轉到:
    • http://localhost:/swagger,以查看 Swagger UI。
    • http://localhost:/swagger/v1/swagger.json,以查看 Swagger 規範。

代碼生成

若要利用 NSwag 的代碼生成功能,可選擇以下選項之一:

  • NSwagStudio – 一款 Windows 桌面應用,用於以 C# 或 TypeScript 生成 API 客戶端代碼。
  • NSwag.CodeGeneration.CSharp 或 NSwag.CodeGeneration.TypeScript NuGet 包 – 用於在專案中生成代碼。
  • 通過命令列使用 NSwag。
  • NSwag.MSBuild NuGet 包。

使用 NSwagStudio 生成代碼

  • 按照 NSwagStudio GitHub 儲存庫中的說明操作,以安裝 NSwagStudio。

  • 啟動 NSwagStudio,併在“Swagger 規範 URL”文本框中輸入 swagger.json 檔案 URL。 例如,http://localhost:44354/swagger/v1/swagger.json

  • 單擊“創建本地副本”按鈕,以生成 Swagger 規範的 JSON 表示形式。

  • 在“輸出”區域中,單擊選中“C# 客戶端”複選框。 也可以選中“TypeScript 客戶端”或“C# Web API 控制器”,具體視專案而定。 如果選中“C# Web API 控制器”,服務規範會重新生成服務,起到反向生成的作用。

  • 單擊“生成輸出”,以生成 TodoApi.NSwag 專案的完整 C# 客戶端實現。 若要查看生成的客戶端代碼,請單擊“C# 客戶端”選項卡:

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

//———————-

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 _settings;

public TodoClient(System.Net.Http.HttpClient httpClient)
{
_httpClient = httpClient;
_settings = new System.Lazy(() =>
{
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.SwaggerContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.SwaggerLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Swagger UI 顯示版本的信息:

XML 註釋

若要啟用 XML 註釋,請執行以下步驟:

  • Visual Studio
  • Visual Studio for Mac
  • Visual Studio Code

 

  • 在“解決方案資源管理器”中右鍵單擊該專案,然後選擇“編輯 .csproj”。
  • 手動將突出顯示的行添加到 .csproj 檔案:
<PropertyGroup>
  <GenerateDocumentationFile>trueGenerateDocumentationFile>

<NoWarn>$(NoWarn);1591NoWarn>
PropertyGroup>

資料註釋

由於 NSwag 使用反射,且建議的 Web API 操作傳回型別為 ActionResult,因此只能推斷 T 定義的傳回型別。 無法自動推斷其他可能的傳回型別。

請看下麵的示例:

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

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

上述操作將傳回 ActionResult 在操作中,它將傳回 CreatedAtRoute。 由於使用 [ApiController] 屬性修飾控制器,所以也可能出現 BadRequest 響應。 有關詳細信息,請參閱自動 HTTP 400 響應。 使用資料註釋告知客戶端,已知此操作會傳回哪些 HTTP 狀態代碼。 使用以下屬性修飾該操作:

[ProducesResponseType(201)]     // Created
[ProducesResponseType(400)]     // BadRequest

在 ASP.NET Core 2.2 或更高版本中,可使用約定,而不是使用 [ProducesResponseType] 顯式修飾各操作。 有關更多信息,請參見使用 Web API 約定。

Swagger 生成器現在可準確地描述此操作,且生成的客戶端知道呼叫終結點時收到的內容。 建議使用這些屬性來修飾所有操作。

有關 API 操作應傳回的 HTTP 響應的指導原則,請參閱 RFC 7231 規範。

原文地址:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag

赞(0)

分享創造快樂