ongoDB从入门到实战之.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/674069.shtml

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

相关文章

Java并发基础:Deque接口和Queue接口的区别?

核心概念 Deque&#xff08;double ended queue&#xff0c;双端队列&#xff09;和Queue&#xff08;队列&#xff09;都是Java集合框架中的接口&#xff0c;它们用于处理元素的排队和出队&#xff0c;但是它们之间存在一些重要的区别&#xff0c;如下&#xff1a; 1、Queue…

HarmonyOS 创建components目录 定义全局自定义组件导出供整个项目使用

之前我的文章 harmonyOS 自定义组件基础演示讲解 我们讲解了 自定义组件的基础用法 但是 我们是写在单个page文件中的 这样 我们跨文件使用就很不友好了 如下图 指向 ets目录下 创建一个目录 按我们 前端开发以往的习惯 这个目录要叫 components 专门放组件集合的地方 然后 按…

《MySQL 简易速速上手小册》第3章:性能优化策略(2024 最新版)

文章目录 3.1 查询优化技巧3.1.1 基础知识3.1.2 重点案例3.1.3 拓展案例 3.2 索引和查询性能3.2.1 基础知识3.2.2 重点案例3.2.3 拓展案例 3.3 优化数据库结构和存储引擎3.3.1 基础知识3.3.2 重点案例3.3.3 拓展案例 3.1 查询优化技巧 让我们来聊聊如何让你的 MySQL 查询跑得像…

3.3-媒资管理之MinIo分布式文件系统上传视频

文章目录 媒资管理5 上传视频5.1 需求分析5.2 断点续传技术5.2.1 什么是断点续传5.2.2 分块与合并测试5.2.3 视频上传流程5.2.4 minio合并文件测试 5.3 接口定义5.4 上传分块开发5.4.1 DAO开发5.4.2 Service开发5.4.2.1 检查文件和分块5.4.2.2 上传分块5.4.2.3 上传分块测试 5.…

高并发对于服务器性能有什么要求?

随着互联网的普及和应用程序的复杂度增加&#xff0c;高并发已经成为许多应用程序必须面对的问题。高并发是指在短时间内有大量用户同时访问应用程序或数据库&#xff0c;对服务器性能提出了更高的要求。本文将探讨高并发对于服务器性能的要求。 一、高并发对服务器硬件的要求…

【Fabric.js】监听画布or元素的点击、选中、移动、添加、删除销毁、变形等各事件

在fabric使用过程中&#xff0c;如果想要玩各种花样&#xff0c;那么fabric的事件监听是一定、必须、肯定要掌握&#xff01;&#xff01;&#xff01; 例子就用vue项目组件里的代码&#xff0c;fabric的使用跟vue、react、angular之类的框架都没任何关系&#xff01; 并且本de…

第205篇| 送给新年12条格言,一些有用的废话

这是2024年一月份flomo和notion 上聚合的系列文章 (01)&#xff1b; 具体方法用的是这个 &#xff1a; 【知识沙虫&#xff0c;一个简单易用的知识体系建模工具】https://mp.weixin.qq.com/s/V2Cdq-1PbMQYvpE4o9NLpQ 首先&#xff0c;方法用下来还是很给力的。输出很快。不过前…

SERVLET过滤器

SERVLET过滤器 全球因特网用户使用不同类型的Web浏览器访问应用服务器上存储的Web应用程序。每个浏览器根据对应的Web浏览器窗口中的设置显示应用程序中的信息。Web应用程序可能会有一些客户机的Web浏览器不支持的HTML标记或功能。这种情况下,应用程序在客户机的Web浏览器中可…

MIMIC-IV官方视图解析 - AKI 肌酐 (kdigo_creatinine、kdigo_stages)

判断AKI我们可以通过肌酐和尿量两个指标来看&#xff0c; 今天我们主要提取肌酐。 kidgo指南的表格 AKI诊断标准&#xff1a;符合以下情况之一者即可被诊断为AKI&#xff1a;①48小时内Scr升高超过26.5μmol/L(0.3mg/dl)&#xff1b;②Scr升高超过基线1.5倍——确认或推测为7…

利用Intersection Observer实现图片懒加载性能优化

ntersection Observer是浏览器所提供的一个 Javascript API&#xff0c;用于异步的检测目标元素以及祖先或者是顶级的文档视窗的交叉状态 这句话的意思就是&#xff1a; 我们可以看的图片当中&#xff0c;绿色的 target element&#xff08;目标元素&#xff09;&#xff0c;…

删除和清空Hive外部表数据

外部表和内部表区别 未被external修饰的是内部表&#xff08;managed table&#xff09;&#xff0c;被external修饰的为外部表&#xff08;external table&#xff09;&#xff1b; 区别&#xff1a; 内部表数据由Hive自身管理&#xff0c;外部表数据由HDFS管理&#xff1b; …

SpringBoot和SpringMVC

目录 一、springboot项目 &#xff08;1&#xff09;创建springboot项目 &#xff08;2&#xff09;目录介绍 &#xff08;3&#xff09;项目启动 &#xff08;4&#xff09;运行一个程序 &#xff08;5&#xff09;通过其他方式创建和运行springboot项目 二、SpringMVC…

高可用 k8s 1.29 一键安装脚本, 丝滑至极

博客原文 文章目录 集群配置配置清单集群规划集群网络规划 环境初始化主机配置 配置高可用ApiServer安装 nginx安装 Keepalived 安装脚本需要魔法的脚本不需要魔法的脚本配置自动补全加入其余节点 验证集群 集群配置 配置清单 OS&#xff1a; ubuntu 20.04kubernetes&#xf…

【Scala】1. 变量和数据类型

1. 变量和数据类型 1.1 for begining —— hello world 新建hello.scala文件&#xff0c;注意object名字与文件名一致。 object hello { def main(args:Array[String]): Unit { println("hello world!") } }运行后打印结果如下&#xff1a; hello world!Pr…

【射影几何13 】梅氏定理和塞瓦定理探讨

梅氏定理和塞瓦定理 目录 一、说明二、梅涅劳斯&#xff08;Menelaus&#xff09;定理三、塞瓦(Giovanni Ceva&#xff09;定理四、塞瓦点的推广4.1 共线定理4.2 三角形外的塞瓦点 一、说明 在射影几何中&#xff0c;梅涅劳斯&#xff08;Menelaus&#xff09;定理和塞瓦定理是…

最大子数组和[中等]

一、题目 给定一个长度为n的环形整数数组nums&#xff0c;返回nums的非空 子数组 的最大可能和 。 环形数组 意味着数组的末端将会与开头相连呈环状。形式上&#xff0c;nums[i]的下一个元素是nums[(i 1) % n]&#xff0c;nums[i]的前一个元素是nums[(i - 1 n) % n]。 子数…

论文封面下划线总是对不齐,这3步你肯定没做!

论文封面 在写论文时&#xff0c;总会遇到论文封面下划线对不齐&#xff0c;学会下面这三招轻松搞定封面。 解决方法 ①选中文字&#xff0c;点击“插入”&#xff0c;选择“表格”&#xff0c;找到“文本转化为表格”。列数为2&#xff0c;文字分割位置选空格&#xff0c;设置…

第21讲:动态内存管理

1.为什么要有动态内存分配 2.malloc和free 3.calloc 4.realloc 5.笔试题 6.总结c/c中程序内存区域划分 1.为什么要有动态内存分配 为了调整申请的空间大小&#xff0c;使程序员可以申请和释放空间&#xff0c;提高程序的灵活性 2.malloc和free 作用&#xff1a;分配一块…

深入了解Redis:选择适用于你的场景的持久化方案

自然语言处理的发展 文章目录 自然语言处理的发展强烈推荐前言&#xff1a;Redis提供了几种主要的持久化方案&#xff1a;RDB快照持久化&#xff1a;工作原理&#xff1a; AOF日志文件持久化&#xff1a;混合持久化&#xff1a; 总结强烈推荐专栏集锦写在最后 强烈推荐 前些天…

相机图像质量研究(7)常见问题总结:光学结构对成像的影响--镜片固化

系列文章目录 相机图像质量研究(1)Camera成像流程介绍 相机图像质量研究(2)ISP专用平台调优介绍 相机图像质量研究(3)图像质量测试介绍 相机图像质量研究(4)常见问题总结&#xff1a;光学结构对成像的影响--焦距 相机图像质量研究(5)常见问题总结&#xff1a;光学结构对成…