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

追逐时光者

发布于 2023-01-05 15:43:12

1.2K0

发布于 2023-01-05 15:43:12

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;
});

解决SwaggerUnable 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();