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.mzph.cn/news/686547.shtml

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

相关文章

前端秘法进阶篇----这还是我们熟悉的浏览器吗?(浏览器的渲染原理)

前端秘法进阶篇----这还是我们熟悉的浏览器吗?(浏览器的渲染原理)

目录 一.浏览器渲染原理 二.渲染时间点 三.渲染流水线 1.解析html(Parse HTML) 1.1解析成DOM树(document object model) 1.2解析成CSSOM树(css object model) 2.样式计算(Recalculate Style) 3.布局(Layout) 4.分层(Layer) 5. 绘制(Paint) 6.分块(Tiling) 7. 光栅化…
阅读更多...
partial的使用举例

partial的使用举例

functools模块中的partial函数用于部分应用&#xff08;partial application&#xff09;一个函数的参数&#xff0c;即固定函数的部分参数&#xff0c;从而返回一个新的函数。 下面是一个使用partial函数的示例&#xff1a; python from functools import partial # 定义一…
阅读更多...
360可视门铃双摄版恢复案例

360可视门铃双摄版恢复案例

家用的智能摄像头恢复了很多&#xff0c;但是可视门铃的恢复却是第一次&#xff0c;现代社会似乎已经全方位处于监控网络之下。360的产品很多&#xff0c;可视门铃只是其众多品牌中的一个&#xff0c;这个案例能让我们窥视到360的开发小精产品的理念。 故障存储: 64G TF卡/ex…
阅读更多...
python入门：常用模块—shutil 模块

python入门：常用模块—shutil 模块

高级的 文件、文件夹、压缩包 处理模块 shutil.copyfileobj(fsrc, fdst[, length]) 将文件内容拷贝到另一个文件中 1 2 mport shutil shutil.copyfileobj(open(old), open(new, w)) shutil.copyfile(src, dst) 拷贝文件 1 shutil.copyfile(f1.log, f2.log) # 拷贝文件&…
阅读更多...
时序预测 | Matlab实现BO-LSSVM贝叶斯算法优化最小二乘支持向量机时间序列预测

时序预测 | Matlab实现BO-LSSVM贝叶斯算法优化最小二乘支持向量机时间序列预测

时序预测 | Matlab实现BO-LSSVM贝叶斯算法优化最小二乘支持向量机时间序列预测 目录 时序预测 | Matlab实现BO-LSSVM贝叶斯算法优化最小二乘支持向量机时间序列预测预测效果基本介绍程序设计参考资料 预测效果 基本介绍 Matlab实现BO-LSSVM贝叶斯算法优化最小二乘支持向量机时间…
阅读更多...
函数、极限、连续——刷题（5

函数、极限、连续——刷题（5

目录 1.题目&#xff1a;2.解题思路和步骤&#xff1a;3.总结&#xff1a;小结&#xff1a; 1.题目&#xff1a; 2.解题思路和步骤&#xff1a; 首先可能想到的是答案为0&#xff0c;但是不可以把 直接化简为n 这里要用到分子分母的平方差&#xff0c;sin^2的周期为π&#x…
阅读更多...
计算机网络——14CDN

计算机网络——14CDN

CDN 视频流化服务和CDN&#xff1a;上下文 视频流量&#xff1a;占据着互连网大部分的带宽 Netflix&#xff0c;YouTube&#xff1a;占据37%&#xff0c;16%的下行流量 挑战&#xff1a;规模性-如何服务~1B用户&#xff1f; 单个超级服务器无法提供服务&#xff08;为什么&am…
阅读更多...
函数、极限、连续——刷题（4

函数、极限、连续——刷题（4

目录 1.题目&#xff1a;2.解题思路和步骤&#xff1a;3.总结&#xff1a;小结&#xff1a; 1.题目&#xff1a; 2.解题思路和步骤&#xff1a; 记住这个公式即可&#xff1a; 所以就很容易求解了&#xff1a; 3.总结&#xff1a; 记住这个公式即可&#xff1a; 小结&am…
阅读更多...
祝所有的CSDN社区成员们新年快乐

祝所有的CSDN社区成员们新年快乐

文章目录 尊敬的CSDN社区成员们&#xff0c; 在新年的钟声即将敲响之际&#xff0c;我携带着满心祝福与期许&#xff0c;以字为舟&#xff0c;穿越虚拟与现实的界限&#xff0c;来到您的身边&#xff0c;向每一位热爱编程、投身技术研究、在CSDN平台上挥洒智慧和汗水的朋友们&a…
阅读更多...
如何使用iptables或者firewalld配置Linux系统的防火墙策略

如何使用iptables或者firewalld配置Linux系统的防火墙策略

在网络安全中&#xff0c;防火墙是一种关键的安全设备&#xff0c;用于保护计算机网络免受恶意攻击和未经授权的访问。在Linux系统中&#xff0c;我们可以使用iptables或者firewalld来配置防火墙策略。本文将介绍如何使用这两种工具来配置Linux系统的防火墙策略&#xff0c;包括…
阅读更多...
Spring Cloud Hystrix：服务容错与熔断

Spring Cloud Hystrix：服务容错与熔断

1. 理解服务容错与熔断 1.1 服务容错的概念和重要性 在分布式系统中&#xff0c;由于各种原因&#xff08;例如网络延迟、服务故障等&#xff09;&#xff0c;服务之间的通信可能会出现故障或者延迟。为了提高系统的可用性和稳定性&#xff0c;需要实现服务容错机制&#xff…
阅读更多...
数据结构:4_二叉树

数据结构:4_二叉树

二叉树 一.树概念及结构 1. 树的概念 树是一种非线性的数据结构&#xff0c;它是由n&#xff08;n>0&#xff09;个有限结点组成一个具有层次关系的集合。把它叫做树是因为它看起来像一棵倒挂的树&#xff0c;也就是说它是根朝上&#xff0c;而叶朝下的。 有一个**特殊的…
阅读更多...
17.3.1.6 自定义处理

17.3.1.6 自定义处理

版权声明&#xff1a;本文为博主原创文章&#xff0c;转载请在显著位置标明本文出处以及作者网名&#xff0c;未经作者允许不得用于商业目的。 模拟某款图像处理软件的处理&#xff0c;它只留下红色、绿色或者蓝色这样的单一颜色。 首先按照颜色划分了6个色系&#xff0c;分别…
阅读更多...
基于Arduino UNO设计一个温控制系统

基于Arduino UNO设计一个温控制系统

目录 概述 1 硬件结构 1.1 整体硬件介绍 1.2 硬件连接结构 2 软件设计 2.1 软件功能介绍 2.2 关于Arduino的一些知识点 2.2.1 定时器 2.2.2 PWM 2.3 代码实现 2.3.1 编译工具 2.3.2 详细代码 3 测试 3.1 温度数据监控 3.2 温控测试 概述 本文介绍如何使用Ardui…
阅读更多...
Rust 语言学习杂谈 (end) (各种工作中遇到的疑难杂症)

Rust 语言学习杂谈 (end) (各种工作中遇到的疑难杂症)

1.在运行 “cargo build --release” 的时候&#xff0c;到底发生了什么&#xff1f; 源 (GPT4.0) : 当我们运行 cargo build --release 命令时&#xff0c;实际上在进行一系列复杂的步骤来编译和构建 Rust 项目的发布版本。这个过程大致可以分解为以下几个步骤&#xff1a;…
阅读更多...
MCU电源控制(PWR)与低功耗

MCU电源控制(PWR)与低功耗

目录 一、STM32 的内核和外设电源系统管理&#xff1a; 二、MCU电源监控&#xff1a; 三、三种低功耗模式&#xff1a; 1、睡眠模式&#xff1a; 2、停止模式&#xff1a; 3、待机模式&#xff1a; 一、STM32 的内核和外设电源系统管理&#xff1a; ① 电池备份区域&#…
阅读更多...
关于预训练模型的一点感悟

关于预训练模型的一点感悟

最近&#xff0c;Yann LeCun 在 WGS 上说&#xff1a; 目前的LLM不可能走到AGI&#xff0c;原因很简单&#xff0c;现在训练这些LLM所使用的数据量为10万亿个令牌&#xff0c;也就是130亿个词&#xff0c;如果你计算人类阅读这些数据需要多长时间&#xff0c;一个人每天阅读8小…
阅读更多...
String讲解

String讲解

文章目录 String类的重要性常用的方法常用的构造方法String类的比较字符串的查找转化数字转化为字符串字符串转数字 字符串替换字符串的不可变性 字符串拆分字符串截取字符串修改 StringBuilder和StringBuffer String类的重要性 在c/c的学习中我们接触到了字符串&#xff0c;但…
阅读更多...
MFC提示 未在此计算机上注册ActiveX控件“{648A5600-2C6E-101B-82B6-000000000014}“完美解决

MFC提示 未在此计算机上注册ActiveX控件“{648A5600-2C6E-101B-82B6-000000000014}“完美解决

&#x1f482; 个人主页:pp不会算法^ v ^ &#x1f91f; 版权: 本文由【pp不会算法v】原创、在CSDN首发、需要转载请联系博主 &#x1f4ac; 如果文章对你有帮助、欢迎关注、点赞、收藏(一键三连)和订阅专栏哦 运行一个mfc老项目的时候出现了这个问题 问题原因: 少了一个文件 …
阅读更多...
【开源图床】使用Typora+PicGo+Github+CDN搭建个人博客图床

【开源图床】使用Typora+PicGo+Github+CDN搭建个人博客图床

准备工作&#xff1a; 首先电脑得提前完成安装如下&#xff1a; 1. nodejs环境(node ,npm):【安装指南】nodejs下载、安装与配置详细教程 2. Picgo:【安装指南】图床神器之Picgo下载、安装与配置详细教程 3. Typora:【安装指南】markdown神器之Typora下载、安装与无限使用详细教…
阅读更多...
最新文章

Copyright @ 2022~2023