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<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 表示形式。

    640?wx_fmt=png

  • 在“输出”区域中,单击选中“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
640?wx_fmt=jpeg

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/316571.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Acwing 276. I-区域

Acwing 276. I-区域 题意&#xff1a; 在 NM 的矩阵中&#xff0c;每个格子有一个权值&#xff0c;要求寻找一个包含 K 个格子的凸连通块&#xff08;连通块中间没有空缺&#xff0c;并且轮廓是凸的&#xff09;&#xff0c;使这个连通块中的格子的权值和最大。 注意&#xf…

开源Dapper的Lambda扩展-Sikiro.Dapper.Extension V2.0

去年我在业余时间&#xff0c;自己整了一套dapper的lambda表达式的封装&#xff0c;原本是作为了一个个人的娱乐项目&#xff0c;当时也只支持了Sql Server数据库。随之开源后&#xff0c;有不少朋友也对此做了试用&#xff0c;也对我这个项目提出了不少的建议。因此我在最近公…

Acwing 277. 饼干

Acwing 277. 饼干 题意&#xff1a; 圣诞老人共有 M 个饼干&#xff0c;准备全部分给 N 个孩子。 每个孩子有一个贪婪度&#xff0c;第 i 个孩子的贪婪度为 g[i]。 如果有 a[i] 个孩子拿到的饼干数比第 i 个孩子多&#xff0c;那么第 i 个孩子会产生 g[i]a[i] 的怨气。 给…

Docker最全教程之使用 Visual Studio Code玩转Docker(二十一)

VS Code是一个年轻的编辑器&#xff0c;但是确实是非常犀利。通过本篇&#xff0c;老司机带你使用VS Code玩转Docker——相信阅读本篇之后&#xff0c;无论是初学者还是老手&#xff0c;都可以非常方便的玩转Docker了&#xff01;所谓是“工欲善其事必先利其器”&#xff0c;VS…

【送书活动】10分钟了解Docker,运维和开发视角有什么不同?

Docker 是 Golang 编写的&#xff0c; 自 2013 年推出以来&#xff0c;受到越来越多的开发者的关注。如今Docker无处不在&#xff0c;这是不争的事实。开发人员都很喜欢它&#xff0c;运维工程师也需要它。他们都需要深入了解如何在关键业务环境中构建和维护符合生产级别要求的…

可持久化(二)

文章目录【可持久化值域线段树/主席树】主席树代码【二维数点】例题【可持久化值域线段树/主席树】 P3834 【模板】可持久化线段树 1&#xff08;主席树&#xff09; 查询序列区间第k小&#xff0c;静态在线。给定 n 个整数构成的序列&#xff0c;将对于指定的闭区间查询其区间…

.NET Core / C# 开发 IOT 嵌入式设备的个人见解

( .NET Core 七龙珠 )一、IOT 平台的支持先看国内优秀的云计算IOT平台(不含QQ互联、小米IOT等针对特定产品的开发者平台&#xff0c;仅列出部分云计算厂商的IOT平台)阿里云 IOThttps://iot.aliyun.com/华为物联网https://developer.huawei.com/ict/cn/site-iot-next腾讯云 物联…

[NewLife.XCode]增量累加

NewLife.XCode是一个有10多年历史的开源数据中间件&#xff0c;支持nfx/netstandard&#xff0c;由新生命团队(2002~2019)开发完成并维护至今&#xff0c;以下简称XCode。整个系列教程会大量结合示例代码和运行日志来进行深入分析&#xff0c;蕴含多年开发经验于其中&#xff0…

膜拜大丹(结论+二元环)

problem 有两个国家&#xff0c;国家 AAA 有 nnn 座城市&#xff0c;国家 BBB 有 mmm 座城市&#xff0c;两个国家间有若干条单向航线。 具体地&#xff0c;有长度为 nnn 的数组 aaa 和长度为 mmm 的数组 bbb。国家 AAA 的第 iii 座城市有单向航线可以到达国家 BBB 的 1∼ai1…

[NewLife.XCode]脏数据

NewLife.XCode是一个有10多年历史的开源数据中间件&#xff0c;支持nfx/netstandard&#xff0c;由新生命团队(2002~2019)开发完成并维护至今&#xff0c;以下简称XCode。整个系列教程会大量结合示例代码和运行日志来进行深入分析&#xff0c;蕴含多年开发经验于其中&#xff0…

你真的了解用户吗?-浅谈《用户画像》的意义和方法

作者&#xff1a;陈炯关于作者系统集成项目管理高级工程师某大型国有银行高级质量管理师从事IT项目管理工作十余年具有丰富的开发与管理经验公司内部敏捷转型的发起者之一深度参与敏捷实践与总结大学校园里流传最广的一句话是什么&#xff1f;“防火防狼防师兄”。为什么师兄这…

Script Lab 续:为 Officejs 开发配置 VSCode 环境

垫场AA&#xff1a;深度&#xff1a;从 Office 365 新图标来看微软背后的设计新理念--------------------------------------------------前期01&#xff1a;尝试&#xff1a;Script Lab&#xff0c;快速 Office 365 开发工具前期02&#xff1a;尝试&#xff1a;Script Lab&…

编程方式重启 ASP.NET Core 网站

点击上方蓝字关注“汪宇杰博客”常言道&#xff0c;多喝热水&#xff0c;重启试试。有时候当应用工作不正常&#xff0c;重启也许能解决问题。但是程序员通常接触不到服务器系统权限。而运维人员和公司流程经常人为制造麻烦阻止我们去重启应用。老实的程序员不善言辞交际&#…

.NET Core 容器化调查

前几天在微信朋友圈做了一个简单的调查&#xff0c;参与人数有500人&#xff0c;调查结果如下&#xff1a;使用K8S的比例非常类似于2017年初我在公众号里针对.NET Core的使用情况的比例。.NET Core是针对云原生应用开发而重新设计的一个平台&#xff0c;.NET Core借鉴了.NET Fr…

NET Core微服务之路:再谈分布式系统中一致性问题分析

前言一致性&#xff1a;很多时候表现在IT系统中&#xff0c;通常在分布式系统中&#xff0c;必须&#xff08;或最终&#xff09;为多个节点的数据保持一致。世间万物&#xff0c;也有存在相同的特征或相似&#xff0c;比如儿时的双胞胎&#xff0c;一批工厂流水线的产品&#…

使用 Nexus3镜像搭设私有仓库(Bower 、Docker、Maven、npm、NuGet、Yum、PyPI)

Docker - 使用 Nexus3 搭设私有 NuGet 仓库Nexus 默认帐号Repositories上传组件包(Package)Repositories 说明准备 Package上传 Package使用 Package拉取 Nexus 镜像运行 NexusNuGetNexus 私有仓库前言说明安装Nexus NuGet 仓库简单使用总结前言NuGetNuget 是免费、开源的包管理…

P3293 [SCOI2016]美味

P3293 [SCOI2016]美味 题意&#xff1a; 有n个数组a&#xff0c;现在有m个询问&#xff0c;每次给出一个b和x&#xff0c;问b xor (a[i] x)的最大值是多少&#xff1f; 题解&#xff1a; 不难看出01Trie的题目 我们设ansa[i]x,我们想要b xor ans的最大值&#xff0c;这个很…

EF Core 小坑:DbContextPool 会引起数据库连接池连接耗尽

DbContextPool 是 ASP.NET Core 2.1 引入的新特性&#xff0c;可以节省创建 DbContext 实例的开销&#xff0c;但没有想到其中藏着一个小坑。最近有一个 ASP.NET Core 项目持续运行一段时间后日志中就会出现数据库连接池达到最大连接数限制的错误&#xff1a;System.InvalidOpe…

Kubernetes架构为什么是这样的?

小编序&#xff1a;在上周发布的《从“鸿沟理论”看云原生&#xff0c;哪些技术能够跨越鸿沟&#xff1f;》一文中&#xff0c;灵雀云CTO陈恺表示&#xff1a;Kubernetes在云计算领域已经成为既定标准&#xff0c;进入主流市场&#xff0c;最新版本主要关注在稳定性、可扩展性方…

开源 , KoobooJson一款高性能且轻量的JSON框架

在C#领域&#xff0c;有很多成熟的开源JSON框架&#xff0c;其中最著名且使用最多的是 Newtonsoft.Json ,然而因为版本迭代,其代码要兼容从net2.0到现在的最新的net框架,并且要支持.net平台下的其它语言,所以最新发布版本的Newtonsoft.Json其dll大小接近700k,另一方面,因为其复…