ASP.NET Core 中使用Swashbuckle

最新推荐文章于 2025-03-23 09:14:26 发布

dotNET跨平台

最新推荐文章于 2025-03-23 09:14:26 发布

阅读量287

点赞数

文章标签： asp.net 后端

版权

在AspNet Core中Swashbuckle主要有三个核心组件：

1.Swagger中间件

首先我们需要安装一下Swashbuckle.AspNetCore NuGet包

接着在启动项中配置Swagger中间件：

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

启用中间件：

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

启动应用程序，我们发现页面上有个链接地址：

https://localhost:<port>/swagger/v1/swagger.json, 我们打开该链接地址，发现json文件正是我们上节所描述的OpenAPI 规范

https://localhost:<port>/swagger/index.html 地址是Swagger UI的默认地址，我们可以修改该地址直接指向到根目录，如下地址移除了swagger段

Swagger ui 地址访问如下：

默认情况下Swashbuckle生成的OpenAPI的规范是基于3.0，我们可以通过修改其版本号来向后兼容别的应用程序：

2.自定义和拓展

2.1 API描述信息

我们可以在Swagger UI文档上添加一些基础描述信息，例如：作者，许可证，描述等

我们看到我们信息被添加到了页面上面：

2.2 xml描述

在项目中启用xml描述：

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

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

禁用该警告有两种方法

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

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

在目录下会生成一个xml文件，我们配置一下Swagger加载这个xml文件，注意在大小写的区别针对Window和Linux

加载xml文件：

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

2.3 数据注解

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

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

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

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

下面链接地址是微软提供我们比较简短的文档告诉我们如何使我们的api文档变得更加丰富：

https://learn.microsoft.com/en-us/training/modules/improve-api-developer-experience-with-swagger/

源代码地址：

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