Swagger是什么?
Swagger是一个规范且完整API文档管理框架,可以用于生成、描述和调用可视化的RESTful风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。
Swagger应用场景
- 如果你的 RESTful API 接口都开发完成了,你可以用 Swagger-editor 来编写 API 文档( yaml 文件 或 json 文件),然后通过 Swagger-ui 来渲染该文件,以非常美观的形式将你的 API 文档,展现给你的团队或者客户。
- 如果你的 RESTful API 还未开始,也可以使用 Swagger ,来设计和规范你的 API,以 Annotation (注解)的方式给你的源代码添加额外的数据。这样,Swagger 就可以检测到这些数据,自动生成对应的 API 文档。
MongoDB从入门到实战的相关教程
MongoDB从入门到实战之MongoDB简介👉
MongoDB从入门到实战之MongoDB快速入门👉
MongoDB从入门到实战之Docker快速安装MongoDB👉
MongoDB从入门到实战之MongoDB工作常用操作命令👉
MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统(1)-后端项目框架搭建👉
MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统(2)-Swagger框架集成👉
YyFlight.ToDoList项目源码地址
欢迎各位看官老爷review,有帮助的别忘了给我个Star哦💖!!!
GitHub地址:GitHub - YSGStudyHards/YyFlight.ToDoList: 【.NET8 MongoDB 待办清单系统】.NET8 MongoDB从入门到实战基础教程,该项目后端使用的是.NET8、前端页面使用Blazor、使用MongoDB存储数据,更多相关内容大家可以看目录中的MongoDB从入门到实战的相关教程。该系列教程可作为.NET Core入门项目进行学习,感兴趣的小伙伴可以关注博主和我一起学习共同进步。
Swashbuckle.AspNetCore框架介绍
GitHub源码地址:GitHub - domaindrivendev/Swashbuckle.AspNetCore: Swagger tools for documenting API's built on ASP.NET Core
Swashbuckle包含了Swagger UI 的嵌入式版本,因此我们可使用中间件注册调用将该嵌入式版本托管在 ASP.NET Core 应用中使用。
Swashbuckle三个主要组件
-
Swashbuckle.AspNetCore.Swagger:将
SwaggerDocument
对象公开为 JSON 终结点的 Swagger 对象模型和中间件。 -
Swashbuckle.AspNetCore.SwaggerGen:从路由、控制器和模型直接生成
SwaggerDocument
对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合,以自动公开 Swagger JSON。 -
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。
Swashbuckle包安装
选择工具=>NuGet包管理器=>程序包管理控制台
输入以下命令安装包:Install-Package Swashbuckle.AspNetCore -Version 6.2.3
添加并配置Swagger中间件
1、将 Swagger生成器添加到 Program.cs
中的服务容器中:
// 添加Swagger服务 builder.Services.AddSwaggerGen(options => {//注意这里的第一个v1,v一定要是小写 否则后面swagger无法正常显示options.SwaggerDoc("v1", new OpenApiInfo { Title = "YyFlight.ToDoList API", Version = "V1" }); });
2、在 Program.cs
中,启用中间件为生成的 JSON 文档和 Swagger UI 提供服务:
注意:要在应用的根 (https://localhost:<port>/
) 处提供 Swagger UI,请将 RoutePrefix
属性设置为空字符串!!
// 添加Swagger相关中间件 app.UseSwagger(); app.UseSwaggerUI(options => {options.SwaggerEndpoint("/swagger/v1/swagger.json", "V1");options.RoutePrefix = string.Empty; });
解决[Swagger]Unable to resolve service for type 'Microsoft.AspNetCore.Mvc.ApiExplorer.IApiDescriptionGroupCollectionProvider' while attempting to activate
启动调试项目,报以下异常:
System.AggregateException:“Some services are not able to be constructed (Error while validating the service descriptor 'ServiceType: Swashbuckle.AspNetCore.Swagger.ISwaggerProvider Lifetime: Transient ImplementationType: Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator': Unable to resolve service for type 'Microsoft.AspNetCore.Mvc.ApiExplorer.IApiDescriptionGroupCollectionProvider' while attempting to activate 'Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator'.) (Error while validating the service descriptor 'ServiceType: Microsoft.Extensions.ApiDescriptions.IDocumentProvider Lifetime: Singleton ImplementationType: Microsoft.Extensions.ApiDescriptions.DocumentProvider': Unable to resolve service for type 'Microsoft.AspNetCore.Mvc.ApiExplorer.IApiDescriptionGroupCollectionProvider' while attempting to activate 'Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator'.)”
参考解决方案:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio
需要在 Program.cs
中的服务容器中添加以下代码:
builder.Services.AddMvc(); 或者 builder.Services.AddEndpointsApiExplorer();
原因:Swashbuckle 依赖于 MVC 的 Microsoft.AspNetCore.Mvc.ApiExplorer 来发现路由和终结点。 如果项目调用 AddMvc,则自动发现路由和终结点。 调用 AddMvcCore 时,必须显式调用 AddApiExplorer 方法。 有关详细信息,请参阅 Swashbuckle、ApiExplorer 和路由。
修改后重新调试运行成功:
Failed to load API definition解决
//这里面的V1一定要是小写v1services.AddSwaggerGen(options =>{options.SwaggerDoc("v1");});
修改后运行正常:
Swagger自定义和扩展
Swagger 提供了为对象模型进行归档和自定义 UI 以匹配你的主题的选项。
API 信息和说明
传递给 AddSwaggerGen
方法的配置操作会添加诸如作者、许可证和说明的信息。
在 Program.cs
中,导入以下命名空间以使用 OpenApiInfo
类:
// 添加Swagger服务 builder.Services.AddSwaggerGen(options => {options.SwaggerDoc("v1", new OpenApiInfo { Title = "YyFlight.ToDoList API",Version = "V1",Description = "MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统",TermsOfService = new Uri("https://github.com/YSGStudyHards/YyFlight.ToDoList"),Contact = new OpenApiContact{Name = "Example Contact",Url = new Uri("https://github.com/YSGStudyHards/YyFlight.ToDoList")},License = new OpenApiLicense{Name = "Example License",Url = new Uri("https://github.com/YSGStudyHards/YyFlight.ToDoList")}}); });
自定义Swagger UI 显示版本的信息如下所示:
API Swagger添加描述
在 Program.cs
中注入XML相关描述:
注意:将 Swagger 配置为使用按照上述说明生成的 XML 文件。 对于 Linux 或非 Windows 操作系统,文件名和路径区分大小写。 例如,
TodoApi.XML
文件在 Windows 上有效,但在 CentOS 上无效。
// 添加Swagger服务 builder.Services.AddSwaggerGen(options => {options.SwaggerDoc("v1", new OpenApiInfo { Title = "YyFlight.ToDoList API",Version = "V1",Description = "MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统",TermsOfService = new Uri("https://github.com/YSGStudyHards/YyFlight.ToDoList"),Contact = new OpenApiContact{Name = "Example Contact",Url = new Uri("https://github.com/YSGStudyHards/YyFlight.ToDoList")},License = new OpenApiLicense{Name = "Example License",Url = new Uri("https://github.com/YSGStudyHards/YyFlight.ToDoList")}});// 获取xml文件名var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";// 获取xml文件路径var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);// 添加控制器层注释,true表示显示控制器注释options.IncludeXmlComments(xmlPath, true); });
项目右键,选择属性,找到生成下面的输出选中生成包含API文档的文件,如下图所示:
注意:关于XML文档文件路径是需要你先勾选上面生成包含API文档的文件的时候运行项目才会生成该项目的XML文档,然后可以把生成的XML文档放到你想要放到的位置。
为什么要这样设置呢,如果不设置的话,发布时候会出问题,找不到 xml文件!!
关于Swagger Json paths为空问题解决
引入Swagger相关中间件和注入相关服务,运行项目依旧不显示接口,原因是还需要注入Controllers服务,添加如下代码:
builder.Services.AddControllers();
最终Program.cs完整的示例代码和运行效果
using Microsoft.OpenApi.Models; using System.Reflection;var builder = WebApplication.CreateBuilder(args);// Add services to the container.//builder.Services.AddMvc(); builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer();// 添加Swagger服务 builder.Services.AddSwaggerGen(options => {options.SwaggerDoc("v1", new OpenApiInfo { Title = "ToDoList API",Version = "V1",Description = ".NET7使用MongoDB开发ToDoList系统",Contact = new OpenApiContact{Name = "GitHub源码地址",Url = new Uri("https://github.com/YSGStudyHards/YyFlight.ToDoList")}});// 获取xml文件名var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";// 获取xml文件路径var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);// 添加控制器层注释,true表示显示控制器注释options.IncludeXmlComments(xmlPath, true);// 对action的名称进行排序,如果有多个,就可以看见效果了options.OrderActionsBy(o => o.RelativePath); });var app = builder.Build();// Configure the HTTP request pipeline. if (app.Environment.IsDevelopment()) {app.UseDeveloperExceptionPage(); }//使中间件能够将生成的Swagger用作JSON端点. //app.UseSwagger(); app.UseSwagger(c => { c.RouteTemplate = "swagger/{documentName}/swagger.json"; }); //允许中间件为Swagger UI(HTML、JS、CSS等)提供服务,指定swagger JSON端点. app.UseSwaggerUI(options => {options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");options.RoutePrefix = string.Empty; });app.UseHttpsRedirection();app.MapControllers();app.Run();
参考文章
Swashbuckle 和 ASP.NET Core 入门 | Microsoft Learn