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<TodoContext>(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:<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 包。

使用 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# 客戶端”選項卡：

//----------------------
// <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.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

• 在“解決方案資源管理器”中右鍵單擊該項目，然后選擇“編輯 <project_name>.csproj”。

• 手動將突出顯示的行添加到 .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(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

.NET社區新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com

總結

以上是生活随笔為你收集整理的NSwag 和 ASP.NET Core的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。