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

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

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

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

相关文章

同比跌超39%！春节楼市进一步冷却

同比跌超39%！春节楼市进一步冷却

楼市偏冷的基调延续。今年春节假期楼市热度进一步冷却。从各线城市的销售面积来看&#xff0c;正月初一至初六&#xff0c;30城楼市商品房平均成交面积继续下滑至2019年以来新低&#xff0c;较去年下滑39.2%&#xff0c;其中一线、三线均呈现大幅下滑&#xff0c;而二线城市成交…
阅读更多...
链式结构实现队列

链式结构实现队列

链式结构实现队列 1.队列1.1队列的概念及结构1.2队列的实现 2. 队列的各种函数实现3. 队列的全部代码实现 1.队列 1.1队列的概念及结构 队列&#xff1a;只允许在一端进行插入数据操作&#xff0c;在另一端进行删除数据操作的特殊线性表&#xff0c;队列具有先进先出 FIFO(Fi…
阅读更多...
2024年抖音小店还能做吗？想做好抖音小店就应该这样做！思路分享

2024年抖音小店还能做吗？想做好抖音小店就应该这样做！思路分享

大家好&#xff0c;我是电商花花。 新的一年又来给大家见面&#xff0c;今天花花先祝福大家大吉&#xff0c;新的一年里顺风又顺水。 现在已经正式进入2024年&#xff0c;那么就有一个老生常谈的问题了&#xff0c;就是2024年抖音小店还能做吗&#xff1f;会不会晚&#xff0…
阅读更多...
面向对象编程（一）

面向对象编程（一）

目录 1. 面向对象编程概述(了解) 1.1 程序设计的思路 1.2 由实际问题考虑如何设计程序 2. Java语言的基本元素&#xff1a;类和对象 2.1 类和对象概述 2.2 类的成员概述 2.3面向对象完成功能的三步骤&#xff08;重要&#xff09; 步骤1&#xff1a;类的定义 步骤2&#xff1a;…
阅读更多...
【STM32 CubeMX】I2C中断方式与DMA方式

【STM32 CubeMX】I2C中断方式与DMA方式

文章目录 前言一、I2C中断方式1.1 CubeMX配置I2C中断1.2 I2C中断函数使用Master模式Mem模式 1.3 DMA方式发送和接收CubeMX配置IIC DMA方式Master模式Mem模式 总结 前言 在STM32 CubeMX环境中&#xff0c;I2C&#xff08;Inter-Integrated Circuit&#xff09;通信协议的实现可…
阅读更多...
半导体物理基础-笔记

半导体物理基础-笔记

源内容参考&#xff1a;https://www.bilibili.com/video/BV11U4y1k7zn/?spm_id_from333.337.search-card.all.click&vd_source61654d4a6e8d7941436149dd99026962 半导体物理要解决的四个问题 载流子在哪里&#xff1b;如何获得足够多的载流子&#xff1b;载流子如何运动…
阅读更多...
Day-02-02

Day-02-02

Httpclient测试 安装HTTP Client插件 使用IDEA自带的http接口测试工具——HTTP Client Open in HTTP Client 生成测试用例 点击绿色箭头可以运行测试用例&#xff0c;控制台会输出结果。 保存和修改测试用例 在模块下新建一个api-test包用来存放测试用例&#xff0c;将生…
阅读更多...
第7章 Page446~449 7.8.9智能指针 std::unique_ptr

第7章 Page446~449 7.8.9智能指针 std::unique_ptr

“unique_ptr”是“独占式智能指针” 名字透露身份&#xff0c;“unique_ptr”是“独占式智能指针”。使用它管理前面的O类指针&#xff1a; 演示1&#xff1a; 例中 p 是一个智能指针。其中的“<O>”指明它所指向的数据类型是“O”。除了创建方法不太一样&#xff0c;…
阅读更多...
【C-＞Cpp】由C迈向Cpp（3）

【C-＞Cpp】由C迈向Cpp（3）

正文开始&#xff1a; 目录 &#xff08;一&#xff09;函数重载 &#xff08;1&#xff09;函数重载 &#xff08;2&#xff09;函数重载实现原理 &#xff08;二&#xff09; 引用 &#xff08;1&#xff09;引用 &#xff08;2&#xff09;语法 i &#xff0c;别名&am…
阅读更多...
C#安装CommunityToolkit.Mvvm依赖

C#安装CommunityToolkit.Mvvm依赖

这里需要有一定C#基础&#xff0c; 首先找到右边的解决方案&#xff0c;右键依赖项 然后选择nuget管理 这里给大家扩展一下nuget的国内源&#xff08;https://nuget.cdn.azure.cn/v3/index.json&#xff09; 然后搜自己想要的依赖性&#xff0c;比如CommunityToolkit.Mvvm 再点…
阅读更多...
Kibana：如何嵌入 Kibana 仪表板

Kibana：如何嵌入 Kibana 仪表板

作者&#xff1a;Carly Richmond 像我这样的前端工程师经常提出的要求是将 Kibana 等来源的现有仪表板嵌入到 JavaScript Web 应用程序中。 这是我必须多次执行的任务&#xff0c;因为我们希望快速部署用户生成的视图或允许用户控制给定的视图。 从我们从精彩的开发者社区收到的…
阅读更多...
Git 初学

Git 初学

目录 一、需求的产生 二、版本控制系统理解 1. 认识版本控制系统 2. 版本控制系统分类 &#xff08;1&#xff09;集中式版本控制系统 缺点&#xff1a; &#xff08;2&#xff09;分布式版本控制系统 三、初识 git 四、git 的使用 例&#xff1a;将 “ OLED文件夹 ”…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023