知識星球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
{
[]
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
