MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统（2）-Swagger框架集成

长林吾玊 發表於 2023-1-4 03:43:00

MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统（2）-Swagger框架集成

<h2>Swagger是什么？</h2>
　　Swagger是一个规范且完整API文档管理框架，可以用于生成、描述和调用可视化的RESTful风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
<h2>Swagger应用场景</h2>
<ul class="ul-level-0">
<li>如果你的 RESTful API 接口都开发完成了，你可以用 Swagger-editor 来编写 API 文档（ yaml 文件或 json 文件），然后通过 Swagger-ui 来渲染该文件，以非常美观的形式将你的 API 文档，展现给你的团队或者客户。</li>
<li>如果你的 RESTful API 还未开始，也可以使用 Swagger ，来设计和规范你的 API，以 Annotation （注解）的方式给你的源代码添加额外的数据。这样，Swagger 就可以检测到这些数据，自动生成对应的 API 文档。</li>
</ul>
<h2>MongoDB从入门到实战的相关教程</h2>
MongoDB从入门到实战之MongoDB简介👉
MongoDB从入门到实战之MongoDB快速入门👉
MongoDB从入门到实战之Docker快速安装MongoDB👉
MongoDB从入门到实战之MongoDB工作常用操作命令👉
MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统（1）-后端项目框架搭建👉
MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统（2）-Swagger框架集成👉
<h2>YyFlight.ToDoList项目源码地址</h2>
欢迎各位看官老爷review，有帮助的别忘了给我个Star哦💖！！！
<blockquote>
GitHub地址：https://github.com/YSGStudyHards/YyFlight.ToDoList
</blockquote>
<h2>Swashbuckle.AspNetCore框架介绍</h2>
<blockquote>
GitHub源码地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
</blockquote>
Swashbuckle包含了Swagger UI 的嵌入式版本，因此我们可使用中间件注册调用将该嵌入式版本托管在 ASP.NET Core 应用中使用。
<h2>Swashbuckle三个主要组件</h2>
<ul>
<li>
Swashbuckle.AspNetCore.Swagger：将 <code>SwaggerDocument</code> 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。
</li>
<li>
Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 <code>SwaggerDocument</code> 对象的 Swagger 生成器。它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。
</li>
<li>
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。它包括针对公共方法的内置测试工具。
</li>
</ul>
<h2>Swashbuckle包安装</h2>
选择工具=>NuGet包管理器=>程序包管理控制台
输入以下命令安装包：Install-Package Swashbuckle.AspNetCore -Version 6.2.3
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230103232509241-11311280.png" alt="" loading="lazy">
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230103232721914-1812634061.png" alt="" loading="lazy">
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230103232753652-991658275.png" alt="" loading="lazy">
<h2>添加并配置Swagger中间件</h2>
1、将 Swagger生成器添加到 <code>Program.cs</code> 中的服务容器中：
<div class="cnblogs_code">
<pre>// 添加Swagger服务
builder.Services.AddSwaggerGen(options =>
{ //注意这里的第一个v1，v一定要是小写否则后面swagger无法正常显示
options.SwaggerDoc("v1", new OpenApiInfo { Title = "YyFlight.ToDoList API", Version = "V1" });
});</pre>
</div>
2、在 <code>Program.cs</code> 中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：
注意：要在应用的根 (<code>https://localhost:<port>/</code>) 处提供 Swagger UI，请将 <code>RoutePrefix</code> 属性设置为空字符串！！
<div class="cnblogs_code">
<pre>// 添加Swagger相关中间件
app.UseSwagger();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "V1");
options.RoutePrefix = string.Empty;
});</pre>
</div>
<h2>解决Unable to resolve service for type 'Microsoft.AspNetCore.Mvc.ApiExplorer.IApiDescriptionGroupCollectionProvider' while attempting to activate</h2>
启动调试项目，报以下异常：
<blockquote>
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'.)”
</blockquote>
参考解决方案：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio
需要在 <code>Program.cs</code> 中的服务容器中添加以下代码：
<div class="cnblogs_code">
<pre>builder.Services.AddMvc(); 或者 builder.Services.AddEndpointsApiExplorer();</pre>
</div>
<blockquote>
原因：Swashbuckle 依赖于 MVC 的 Microsoft.AspNetCore.Mvc.ApiExplorer 来发现路由和终结点。如果项目调用 AddMvc，则自动发现路由和终结点。调用 AddMvcCore 时，必须显式调用 AddApiExplorer 方法。有关详细信息，请参阅 Swashbuckle、ApiExplorer 和路由。
</blockquote>
修改后重新调试运行成功：
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104010211740-823672348.png" alt="" loading="lazy">
 
<h2 class="title">Failed to load API definition解决</h2>
<div class="cnblogs_code">
<pre> //这里面的V1一定要是小写v1
services.AddSwaggerGen(options =>
{
 options.SwaggerDoc("v1");
});</pre>
</div>
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104011828873-203664707.png" alt="" loading="lazy">
 
 修改后运行正常：
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104011912694-1041711483.png" alt="" loading="lazy">
<h2>Swagger自定义和扩展</h2>
Swagger 提供了为对象模型进行归档和自定义 UI 以匹配你的主题的选项。
<h3 id="api-info-and-description" class="heading-anchor">API 信息和说明</h3>
传递给 <code>AddSwaggerGen</code> 方法的配置操作会添加诸如作者、许可证和说明的信息。
在 <code>Program.cs</code> 中，导入以下命名空间以使用 <code>OpenApiInfo</code> 类：
<div class="cnblogs_code">
<pre>// 添加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")
 }
});
});</pre>
</div>
自定义Swagger UI 显示版本的信息如下所示：
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104012020564-64856943.png" alt="" loading="lazy">
 
<h2> API Swagger添加描述</h2>
在 <code>Program.cs</code> 中注入XML相关描述：
<blockquote>
注意：将 Swagger 配置为使用按照上述说明生成的 XML 文件。对于 Linux 或非 Windows 操作系统，文件名和路径区分大小写。例如，<code>TodoApi.XML</code> 文件在 Windows 上有效，但在 CentOS 上无效。
</blockquote>
<div class="cnblogs_code">
<pre>// 添加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);
});</pre>
</div>
项目右键，选择属性，找到生成下面的输出选中生成包含API文档的文件，如下图所示：
<blockquote>
注意：关于XML文档文件路径是需要你先勾选上面生成包含API文档的文件的时候运行项目才会生成该项目的XML文档，然后可以把生成的XML文档放到你想要放到的位置。
</blockquote>
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104015448311-1041077088.png" alt="" loading="lazy">
 为什么要这样设置呢，如果不设置的话，发布时候会出问题，找不到 xml文件！！
 <img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104023723340-1211411073.png" alt="" loading="lazy">
<h2>关于Swagger Json paths为空问题解决</h2>
引入Swagger相关中间件和注入相关服务，运行项目依旧不显示接口，原因是还需要注入Controllers服务，添加如下代码：
<div class="cnblogs_code">
<pre>builder.Services.AddControllers();</pre>
</div>
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104033914181-1980961423.png" alt="" loading="lazy">
 
<h2>最终Program.cs完整的示例代码和运行效果</h2>
<div class="cnblogs_code">
<pre>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();</pre>
</div>
<img src="https://img2023.cnblogs.com/blog/1336199/202301/1336199-20230104034251434-1499239887.png" alt="" loading="lazy">
<h2>参考文章</h2>
https://learn.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-7.0&tabs=visual-studio

</div>
<div id="MySignature" role="contentinfo">
<blockquote >
作者名称：追逐时光者
作者简介：一个热爱编程、善于分享、喜欢学习、探索、尝试新事物和新技术的全栈软件工程师。

本文版权归作者和博客园共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文链接，否则保留追究法律责任的权利。如果该篇文章对您有帮助的话，可以点一下右下角的【&hearts;推荐&hearts;】，希望能够持续的为大家带来好的技术文章，文中可能存在描述不正确的地方，欢迎指正或补充，不胜感激。

</blockquote> 
来源：https://www.cnblogs.com/Can-daydayup/p/17020885.html

頁: [1]

琼殿技术论坛's Archiver

MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统（2）-Swagger框架集成