NSwag 和 ASP.NET Core 入门
作者:Christoph Nienaber、Rico Suter 和 Dave 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 包,请使用以下方法之一:
从“程序包管理器控制台”窗口:
转到“视图”>“其他窗口”>“程序包管理器控制台”
导航到包含
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 规范和 Swagger UI 提供服务:
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:一款 Windows 桌面应用,用于在 C# 或 TypeScript 中生成 API 客户端代码。
- NSwag.CodeGeneration.CSharp 或 NSwag.CodeGeneration.TypeScript NuGet 包 - 用于在项目中生成代码。
- 通过命令行使用 NSwag。
- NSwag.MSBuild NuGet 包。
- Unchase OpenAPI (Swagger) Connected Service(Unchase OpenAPI (Swagger) 连接服务):一种 Visual Studio 连接服务,用于在 C# 或 TypeScript 中生成 API 客户端代码。 还可以使用 NSwag 为 OpenAPI 服务生成 C# 控制器。
使用 NSwagStudio 生成代码
按照 NSwagStudio GitHub 存储库中的说明操作,以安装 NSwagStudio。 在 NSwag 发布页面上,可以下载无需安装和管理员权限即可启动的 xcopy 版本。
启动 NSwagStudio,并在“Swagger 规范 URL”文本框中输入
swagger.json
文件 URL。 例如,http://localhost:44354/swagger/v1/swagger.json
。单击“创建本地副本”按钮,以生成 Swagger 规范的 JSON 表示形式。
在“输出”区域中,单击“CSharp 客户端”复选框 。 也可以选中“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.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 显示版本的信息:
XML 注释
若要启用 XML 注释,请执行以下步骤:
- 在解决方案资源管理器中右键单击该项目,然后选择“
Edit <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(StatusCodes.Status201Created)] // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)] // BadRequest
在 ASP.NET Core 2.2 或更高版本中,可使用约定,而不是使用 [ProducesResponseType]
显式修饰各操作。 有关详细信息,请参阅使用 Web API 约定。
Swagger 生成器现在可准确地描述此操作,且生成的客户端知道调用终结点时收到的内容。 建议使用这些属性来标记所有操作。
有关 API 操作应返回的 HTTP 响应的指南,请参阅 RFC 9110:HTTP 语义(第 9.3 节 - 方法定义)。
作者:Christoph Nienaber、Rico Suter 和 Dave 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 包,请使用以下方法之一:
从“程序包管理器控制台”窗口:
转到“视图”>“其他窗口”>“程序包管理器控制台”
导航到包含
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 规范和 Swagger UI 提供服务:
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:一款 Windows 桌面应用,用于在 C# 或 TypeScript 中生成 API 客户端代码。
- NSwag.CodeGeneration.CSharp 或 NSwag.CodeGeneration.TypeScript NuGet 包 - 用于在项目中生成代码。
- 通过命令行使用 NSwag。
- NSwag.MSBuild NuGet 包。
- Unchase OpenAPI (Swagger) Connected Service(Unchase OpenAPI (Swagger) 连接服务):一种 Visual Studio 连接服务,用于在 C# 或 TypeScript 中生成 API 客户端代码。 还可以使用 NSwag 为 OpenAPI 服务生成 C# 控制器。
使用 NSwagStudio 生成代码
按照 NSwagStudio GitHub 存储库中的说明操作,以安装 NSwagStudio。 在 NSwag 发布页面上,可以下载无需安装和管理员权限即可启动的 xcopy 版本。
启动 NSwagStudio,并在“Swagger 规范 URL”文本框中输入
swagger.json
文件 URL。 例如,http://localhost:44354/swagger/v1/swagger.json
。单击“创建本地副本”按钮,以生成 Swagger 规范的 JSON 表示形式。
在“输出”区域中,单击“CSharp 客户端”复选框 。 也可以选中“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.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 显示版本的信息:
XML 注释
若要启用 XML 注释,请执行以下步骤:
- 在解决方案资源管理器中右键单击该项目,然后选择“
Edit <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(StatusCodes.Status201Created)] // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)] // BadRequest
在 ASP.NET Core 2.2 或更高版本中,可使用约定,而不是使用 [ProducesResponseType]
显式修饰各操作。 有关详细信息,请参阅使用 Web API 约定。
Swagger 生成器现在可准确地描述此操作,且生成的客户端知道调用终结点时收到的内容。 建议使用这些属性来标记所有操作。
有关 API 操作应返回的 HTTP 响应的指南,请参阅 RFC 9110:HTTP 语义(第 9.3 节 - 方法定义)。