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一定要是小写v1
     services.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

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

如若内容造成侵权/违法违规/事实不符,请联系我们进行投诉反馈qq邮箱809451989@qq.com,一经查实,立即删除!

相关文章

JDBC 核心 API

引入 mysql-jdbc 驱动 驱动 jar 版本的选择&#xff1a;推荐使用 8.0.25&#xff0c;省略时区设置java 工程导入依赖 项目创建 lib 文件夹导入驱动依赖 jar 包jar 包右键 - 添加为库 JDBC 基本使用步骤 注册驱动获取连接创建发送 sql 语句对象发送 sql 语句&#xff0c;并获…

清华AutoGPT:掀起AI新浪潮,与GPT4.0一较高下

引言&#xff1a; 随着人工智能技术的飞速发展&#xff0c;自然语言处理&#xff08;NLP&#xff09;领域迎来了一个又一个突破。最近&#xff0c;清华大学研发的AutoGPT成为了业界的焦点。这款AI模型以其出色的性能&#xff0c;展现了中国在AI领域的强大实力。 目录 引言&…

字符串拼接 - 华为OD统一考试(C卷)

OD统一考试&#xff08;C卷&#xff09; 分值&#xff1a; 200分 题解&#xff1a; Java / Python / C 题目描述 给定 M 个字符( a-z ) &#xff0c;从中取出任意字符(每个字符只能用一次)拼接成长度为 N 的字符串&#xff0c;要求相同的字符不能相邻。 计算出给定的字符列表…

突发!亚马逊创始人贝索斯抛售60亿美元股票,外网疑其或加仓比特币

号外&#xff1a;2.16教链内参《内参&#xff1a;OpenAI Sora惊艳发布&#xff0c;加密圈有人获利超700倍》 前世界首富、全球知名电商平台亚马逊&#xff08;amazon&#xff09;创始人杰夫贝索斯&#xff08;Jeff Bezos&#xff09;最近一周以来接连抛售自家公司股票&#xff…

BulingBuling[Beyond the To-Do List] - 《让金钱为你服务》 [ Make Money Work for You ]

与《财务自由: 赚到足够的钱的有效方法》作者Grant的简短访谈 让钱为你工作 超越待办事项清单 主持人&#xff1a;Erik Fisher Make Money Work for You Beyond the To-Do List Hosted by Erik Fisher 与Erik Fisher一起探索如何确定你生活中最大的财务杠杆以及使用它们的最佳方…

【Linux系统化学习】文件重定向

目录 文件内核对象 文件描述符的分配规则 重定向 重定向的概念 dup2系统调用 输出重定向 追加重定向 输入重定向 stderr解析 重定向到同一个文件中 分离常规输出和错输出 文件内核对象 上篇文章中我们介绍到了操作系统中的文件&#xff0c;操作系统为了方…

什么是智慧公厕,智慧公厕有哪些功能

1.什么是智慧公厕&#xff1f; 随着智慧城市的快速发展&#xff0c;公共厕所作为城市基础设施的一部分&#xff0c;也在逐步升级转型。那么&#xff0c;什么是智慧公厕&#xff1f;智慧公厕作为智慧城市的重要组成部分&#xff0c;将公共厕所的建设、设计、使用、运营和管理等…

报错405(errAxiosError: Request failed with status code 405)

errAxiosError: Request failed with status code 405 前端调用接口的方法跟后台定义接口的方法不一致

docker (四)-docker网络

默认网络 docker会自动创建三个网络&#xff0c;bridge,host,none bridge桥接网络 如果不指定&#xff0c;新创建的容器默认将连接到bridge网络。 默认情况下&#xff0c;使用bridge网络&#xff0c;宿主机可以ping通容器ip&#xff0c;容器中也能ping通宿主机。 容器之间只…

UE4学习笔记 FPS游戏制作5 动画蒙太奇制作开枪动画

创建一个蒙太奇 选择角色的骨骼&#xff0c;并重命名 编辑蒙太奇 将我们需要的动画拖动到Default下的两个白杠的上边那个里 然后在下方的Sections节点中&#xff0c;点击Preview后的Default&#xff0c;选中后&#xff0c;再点击PreviewAllScetions上百年的长的绿色的Defalut&…

使用miniconda管理Python环境

之前经常使用pipenv管理虚拟环境&#xff0c;但是有一个问题就是代码给别人使用的时候&#xff0c;别人使用的Python版本和自己的不一致时&#xff0c;安装依赖包的时候会有问题。所以现在使用miniconda来管理虚拟环境&#xff0c;不仅小巧方便&#xff0c;还能为每个环境指定不…

Gitee入门之工具的安装

一、gitee是什么&#xff1f; Gitee&#xff08;码云&#xff09;是由开源中国社区在2013年推出的一个基于Git的代码托管平台&#xff0c;它提供中国本土化的代码托管服务。它旨在为个人、团队和企业提供稳定、高效、安全的云端软件开发协作平台&#xff0c;具备代码质量分析、…

LeetCode 100题目(python版本)待续...

一.哈希 1.两数之和 题目 给定一个整数数组 nums 和一个整数目标值 target&#xff0c;请你在该数组中找出 和为目标值 target 的那 两个 整数&#xff0c;并返回它们的数组下标。 你可以假设每种输入只会对应一个答案。但是&#xff0c;数组中同一个元素在答案里不能重复…

【LeetCode: 103. 二叉树的锯齿形层序遍历 + BFS】

&#x1f680; 算法题 &#x1f680; &#x1f332; 算法刷题专栏 | 面试必备算法 | 面试高频算法 &#x1f340; &#x1f332; 越难的东西,越要努力坚持&#xff0c;因为它具有很高的价值&#xff0c;算法就是这样✨ &#x1f332; 作者简介&#xff1a;硕风和炜&#xff0c;…

QGIS004:【10栅格地形分析工具箱】-坡度、坡向、山体阴影

摘要&#xff1a;QGIS栅格地形分析工具箱常用工具有坡度、坡向、山体阴影等选项&#xff0c;本文介绍各选项的基本操作。 实验数据&#xff1a; 链接&#xff1a;https://pan.baidu.com/s/1gYZ_om4AlSdal0bts2mt-A?pwd4rrn 提取码&#xff1a;4rrn 一、坡度 工具功能&…

VitePress-17- 配置- appearance 的作用详解

作用说明 appearance : 是进行主题模式的配置开关&#xff0c;决定了是否启用深色模式。 可选的配置值&#xff1a; true: 默认配置&#xff0c;可以切换为深色模式&#xff1b; false: 禁用主题切换&#xff0c;只使用默认的配置&#xff1b; dark: 默认使用深色模式&#xff…

软件工程师,超过35岁怎么办

概述 随着科技行业的飞速发展&#xff0c;软件开发工程师的职业道路充满了各种机遇和挑战。对于已经在这个行业摸爬滚打了十多年的软件开发工程师来说&#xff0c;当他们步入35岁这个年纪时&#xff0c;可能会感到一些迷茫和焦虑。许多人担忧&#xff0c;在以创新、活力、快速迭…

SUSAN关键点检测以及SAC-IA粗配准

一、SUSAN关键点检测 C #include <iostream> #include <pcl/io/pcd_io.h> #include <pcl/point_types.h> #include <pcl/common/io.h> #include <pcl/visualization/pcl_visualizer.h> #include <boost/thread/thread.hpp> #include <…

[]人的成功离不开气运这么一说!

这里写自定义目录标题 欢迎使用Markdown编辑器新的改变功能快捷键合理的创建标题&#xff0c;有助于目录的生成如何改变文本的样式插入链接与图片如何插入一段漂亮的代码片生成一个适合你的列表创建一个表格设定内容居中、居左、居右SmartyPants 创建一个自定义列表如何创建一个…

代码随想录刷题笔记-Day17

1. 路径总和 112. 路径总和https://leetcode.cn/problems/path-sum/ 给你二叉树的根节点 root 和一个表示目标和的整数 targetSum 。判断该树中是否存在 根节点到叶子节点 的路径&#xff0c;这条路径上所有节点值相加等于目标和 targetSum 。如果存在&#xff0c;返回 true …