1､安装引用NSwag中间件
为已实现的Web API生成Swagger规范。服务Swagger UI，以浏览和测试Web API。
1) 使用Nuget界面管理器
搜索"NSwag.AspNetCore",在列表中找到它，点击"安装"
相关文档：VS(Visual Studio)中Nuget的使用
2) 使用Package Manager命令安装
PM> Install-Package NSwag.AspNetCore
3) 使用.NET CLI命令安装
> dotnet add TodoApi.csproj package NSwag.AspNetCore
2､添加和配置Swagger中间件
通过执行以下步骤，在ASP.NET Core应用程序中添加和配置Swagger：
1) 在该Startup.ConfigureServices方法中，注册所需的Swagger服务
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc();
// Register the Swagger services
services.AddSwaggerDocument();
}
2) 在该Startup.Configure方法中，启用中间件以服务生成的Swagger规范和Swagger UI
public void Configure(IApplicationBuilder app)
{
app.UseStaticFiles();
// Register the Swagger generator and the Swagger UI middlewares
app.UseOpenApi();
app.UseSwaggerUi3();
app.UseMvc();
}
3) 访问如下地址(Swagger UI和Swagger规范)
Swagger UI：http://localhost:/swagger
Swagger规范：http://localhost:/swagger/v1/swagger.json
3､NSwag代码生成的使用
您可以通过选择以下选项之一来利用NSwag的代码生成功能：
1) NSwagStudio – Windows桌面应用程序，用于以C＃或TypeScript生成API客户端代码
2) 该NSwag.CodeGeneration.CSharp或NSwag.CodeGeneration.TypeScript的NuGet包代码生成您的项目中
3) NSwag命令行
4) NSwag.MSBuild NuGet包
5) 所述Unchase的OpenAPI（Swagger）连接的服务 -在C＃或打字原稿生成API的客户端代码一个Visual Studio连接的服务。还使用NSwag为OpenAPI服务生成C＃控制器。
4､使用NSwagStudio生成代码
1) 按照NSwagStudio GitHub存储库中的说明安装NSwagStudio 。在NSwag发行页面上，您可以下载xcopy版本，该版本无需安装和管理员权限即可启动。
2) 启动NSwagStudio，并在Swagger Specification URL文本框中输入swagger.json文件URL 。例如http://localhost:44354/swagger/v1/swagger.json。
3) 单击“Create local Copy”按钮以生成Swagger规范的JSON表示形式
4) 在"Outputs"区域中，单击“CSharp Client”复选框。根据您的项目，您还可以选择"TypeScript Client"或"CSharp Web API Controller"。如果选择"CSharp Web API Controller"，则服务规范将重建服务，作为反向生成。
5) 单击“Generate Outputs”以生成TodoApi.NSwag项目的完整C#客户端实现。要查看生成的客户端代码，请单击“CSharp Client”选项卡：
//----------------------
// <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#客户端代码是根据“Settings”选项卡中的选择生成的。修改设置以执行诸如默认名称空间重命名和同步方法生成之类的任务。
6) 将生成的C＃代码复制到客户端项目中的文件中，该文件将使用该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);
5､使用NSwag自定义API文档
Swagger提供了用于记录对象模型的选项，以简化Web API的使用。
5､1 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显示版本信息：
5､2 XML注释
要启用XML注释，请执行以下步骤：
1) 在解决方案资源管理器中右键单击该项目，然后选择Edit <project_name>.csproj。
2) 手动将显示的行添加到.csproj文件
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
5､3 数据注解
由于NSwag使用Reflection，并且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 7231规范。
相关文档：
ASP.NET Core Web API Swagger/OpenAPI Swashbuckle.AspNetCore NSwag介绍