MongoDB從入門到實戰之.NET Core使用MongoDB開發ToDoList系統（2）-Swagger框架整合

追逐時光者發表於2023-01-04
MongoDBSwagger框架

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

相關文章