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项目源码地址

GitHub地址:https://github.com/YSGStudyHards/YyFlight.ToDoList

Swashbuckle.AspNetCore框架介绍

GitHub源码地址:https://github.com/domaindrivendev/Swashbuckle.AspNetCore

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自定义和扩展

wagger 提供了为对象模型进行归档和自定义 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();

参考文章

https://learn.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-7.0&tabs=visual-studio

MongoDB从入门到实战之.NET Core使用MongoDB开发ToDoList系统(2)-Swagger框架集成的更多相关文章

  1. Spring Boot 从入门到实战汇总

    之前写过几篇spring boot入门到实战的博文,因为某些原因没能继续. 框架更新迭代很快,之前还是基于1.x,现在2.x都出来很久了.还是希望能从基于该框架项目开发的整体有一个比较系统的梳理,于是 ...

  2. 在.Net Core中使用MongoDB的入门教程(二)

    在上一篇文章中,讲到了MongoDB在导入驱动.MongoDB的连接,数据的插入等. 在.Net Core中使用MongoDB的入门教程(一) 本篇文章将接着上篇文章进行介绍MongoDB在.Net ...

  3. 在.Net Core中使用MongoDB的入门教程(一)

    首先,我们在MongoDB的官方文档中看到,MongoDb的2.4以上的For .Net的驱动是支持.Net Core 2.0的. 所以,在我们安装好了MangoDB后,就可以开始MangoDB的.N ...

  4. 《ASP.NET Core跨平台开发从入门到实战》Web API自定义格式化protobuf

    <ASP.NET Core跨平台开发从入门到实战>样章节 Web API自定义格式化protobuf. 样章 Protocol Buffers 是一种轻便高效的结构化数据存储格式,可以用于 ...

  5. apollo入门demo实战(二)

    1. apollo入门demo实战(二) 1.1. 下载demo 从下列地址下载官方脚本和官方代码 https://github.com/nobodyiam/apollo-build-scripts ...

  6. 《Angular4从入门到实战》学习笔记

    <Angular4从入门到实战>学习笔记 腾讯课堂:米斯特吴 视频讲座 二〇一九年二月十三日星期三14时14分 What Is Angular?(简介) 前端最流行的主流JavaScrip ...

  7. 零基础入门Python实战:四周实现爬虫网站 Django项目视频教程

    点击了解更多Python课程>>> 零基础入门Python实战:四周实现爬虫网站 Django项目视频教程 适用人群: 即将毕业的大学生,工资低工作重的白领,渴望崭露头角的职场新人, ...

  8. 【Python高级工程师之路】入门+进阶+实战+爬虫+数据分析整套教程

    点击了解更多Python课程>>> 全网最新最全python高级工程师全套视频教程学完月薪平均2万 什么是Python? Python是一门面向对象的编程语言,它相对于其他语言,更加 ...

  9. Soap从入门到实战

    Soap从入门到实战 参考文章:https://howtodoinjava.com/spring-boot/spring-soap-client-webservicetemplate/ 使用的技术:s ...

  10. 【新书推荐】《ASP.NET Core微服务实战:在云环境中开发、测试和部署跨平台服务》 带你走近微服务开发

    <ASP.NET Core 微服务实战>译者序:https://blog.jijiechen.com/post/aspnetcore-microservices-preface-by-tr ...

随机推荐

  1. JUC(8)JMM

    文章目录 1.JMM 2.volatile 3.单例模式 1.JMM Volatile是java虚拟机提供轻量级的同步机制 1.保证可见性 2.不保证原子性 3.禁止指令重排 什么是JMM java内 ...

  2. python基础之标识符、注释与变量

    一.注释 1.作用:注释是用来解释和说明代码的. 2.分类:注释可以分为单行注释和多行注释 2.1.单行注释:在编写的代码或文字前加上"#",表示单行注释 1 #我是单行注释 2 ...

  3. Istio(十一):向istio服务网格中引入虚拟机

    目录 一.模块概览 二.系统环境 三.虚拟机负载 3.1 虚拟机负载 3.2 单网络架构 3.3 多网络架构 3.4 Istio 中如何表示虚拟机工作负载? 四.实战:向istio Mesh中引入虚拟 ...

  4. SpringMVC&Maven进阶

    3. SpringMVC 3.1 了解SpringMVC 概述 SpringMVC技术与Servlet技术功能等同,均属于web层开发技术 学习路线 请求与响应 REST分割 SSM整合 拦截器 目标 ...

  5. 【深入浅出 Yarn 架构与实现】2-4 Yarn 基础库 - 状态机库

    当一个服务拥有太多处理逻辑时,会导致代码结构异常的混乱,很难分辨一段逻辑是在哪个阶段发挥作用的. 这时就可以引入状态机模型,帮助代码结构变得清晰. 一.状态机库概述 一)简介 状态机由一组状态组成: ...

  6. hwlog---huawei.com/npu-exporter/utils---utils.go

    // Copyright(C) 2021. Huawei Technologies Co.,Ltd. All rights reserved.// Package utils offer the so ...

  7. i春秋Hash

    打开题目页面是一个超链接 先查看源码得到一段信息 没什么,这只是超链接跳转的信息 点击跳转到下一个界面 提示我们如果我们的传入不是123,123也就是key了,在上面的url就可以看到 如果key!= ...

  8. (C++) C++ 中 shared_ptr weak_ptr

    shared_ptr std::shared_ptr<int> sp1 = new int(); // shared count = 1, weak count = 0 std::shar ...

  9. php7怎么安装memcache扩展

    php7安装memcache扩展 1.下载文件,解压缩 memcache windows php7下载地址: https://github.com/nono303/PHP7-memcache-dll ...

  10. Azure DevOps Server 用户组加入 Azure AD Domain Service 管理用户

    一,引言 今天我们继续讲解 Azure DevOps Server 的内容,对于管理用户组除了在 Azure DevOps Server 服务器上添加管理员方式外,还有没有其他方式,Azure Dev ...