ASP.NET Core 使用NSwag（asp.net machine.account可以删除吗）

wxchong 2024-08-17 01:18:23 开源技术 13 ℃ 0 评论

1. 项目中配置NSwag

我们新建一个项目命名为AspNetCore.NSwag，在项目中添加NSwag.AspNetCore NuGet包

添加和配置Swagger中间件：

运行应用程序，访问如下地址：

https://localhost:<port>/swagger/index.html

https://localhost:<port>/swagger/v1/swagger.json

2.自定义和拓展

2.1 API描述信息

在Program.cs类中更新AddOpenApiDocument方法并配置API文档包含更多的信息，例如：作者，许可证，描述等

这里需要注意OpenApiInfo这个类，在这里我们使用的是NSwag命名空间下，而不是Microsoft.OpenApi.Models这个命名空间下，我们看到我们信息被添加到了页面上面：

2.2 xml描述

在项目中启用xml描述：

选中之后在项目文件中会生成如下标签：

启用之后我们会发现产生警告：

禁用该警告有两种方法

项目中禁止警告，在项目的Project中添加如下标签，这是针对整个项目警告被全部禁止掉：

针对特定成员禁用警告，可以使用#pragma warning 预处理指令将代码括起来：

我们看到我们的注释产生了效果：

2.3 数据注解

我们在TodoItem类中添加如下特性：

在API控制器上添加[Produces("application/json")]特性，该特性表明响应的内容为application/json

接着我们在ProducesResponseType特性来说明Create的api返回的状态码：

运行程序我们来查看一下Swagger UI会生成什么样子

redoc使用OpenAPI的标准为Web API提供了一个文档的页面，用它可以替换Swagger UI，它两不同的是Redoc UI更多的聚焦在文档上，而没有提供在页面上测试api的功能，我们在项目中使用该文档

运行应用程序导航到如下地址https://localhost:<port>/redo

我们可以看到页面上确实没有交互文档，仅仅是一些API展示,有关redoc文档请查看：https://github.com/RicoSuter/NSwag

源代码地址：

https://github.com/bingbing-gui/Asp.Net-Core-Skill/tree/master/Fundamentals/AspNetCore.Swagger/AspNetCore.NSwag

网站首页 > 开源技术正文