.Net Core 3.1瀏覽器後端服務（三） Swagger引入與應用

鹹魚翻身？發表於2021-02-20
瀏覽器後端Swagger

一、前言

前後端分離的軟體開發方式已逐步成為網際網路專案開發的業界標準，前後端分離帶來了諸多好處的同時，也帶來了一些弊端。

介面文件的維護就是其中之一，起初前後端約定文件規範，開發的很愉快，隨著時間推移、版本迭代、介面更改，介面文件維護越來越麻煩。

相信很多前端開發者（請求方）都遇到過實際請求與介面文件不一致的問題

後端開發者（介面提供方）因為時間問題經常來不及更新。
所以僅僅只通過強制來規範大家是不夠的，此時Swagger應運而生

什麼是Swagger?

Swagger是一個強大的介面文件自動生成工具。

二、引入Swagger包

在Package Manager Console輸入如下命令

Install-Package Swashbuckle.AspNetCore -Version 6.0.7

或者在MWebAPI專案右鍵

 

 

選擇最新版本Install，安裝完成後新增Swagger服務注入及中介軟體配置

在Startup類的ConfigureServices方法中新增服務注入：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo {Title = "Net Core API", Version = "v1"});
});

在Startup類的Configure方法中配置Swagger相關中介軟體：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Net Core API");
});

F5執行專案

 咦，Swagger文件並未展示，這是由於預設啟動url未更改

修改launchSetting.json檔案中launchUrl如下：

 再次F5執行

預想的SwaggerUI展示出來了

三、新增註釋

1、首先新增文件說明及作者資訊

修改Swagger服務注入部分

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Net Core API",
        Version = "v1",
        Description = "A simple DotNet core web API sample program",
        Contact = new OpenApiContact
        {
            Name = "Sirius",
            Email = "1247830052@qq.com",
            Url = new Uri("https://www.cnblogs.com/mchao/"),
            Extensions = null,
        },
        License = new OpenApiLicense
        {
            Name = "免費許可",
            Url = new Uri("https://www.cnblogs.com/mchao/"),
            Extensions = null,
        }
    });
});

 執行如下：

2、新增生成Controller的註釋說明

MWebAPI專案右鍵->properties->build->output

 build專案會生成Controller.xml檔案及內容(自動建立更新，無需手動維護)

接著在AddSwaggerGen方法中新增文件路徑

services.AddSwaggerGen(c =>
{var xmlPath = Path.Combine(AppContext.BaseDirectory, "Controller.xml");
    c.IncludeXmlComments(xmlPath, true);
});

執行如下：

 3、新增返回資料的註釋說明

MDto專案右鍵->properties->build->output

接著在AddSwaggerGen方法中新增文件路徑

services.AddSwaggerGen(c =>
{
    var xmlDtoPath = Path.Combine(AppContext.BaseDirectory, "Dto.xml");
    c.IncludeXmlComments(xmlDtoPath, true);
});

執行

這裡有個異常，找不到Dto.xml，目前是這樣處理的，Dto.xml檔案屬性 Copy to Outup Direcotry,如哪位道友有其他方案請告知。。。

 再次執行

 可看到Dto的註釋資訊

四、Api分組

1、增加分組

在Startup類的ConfigureServices方法中增加doc分組：

c.SwaggerDoc("V2", new OpenApiInfo
{
    Title = "Net Core API V2",
    Version = "V2",
    Description = "A simple DotNet core web API sample program2",
});

在Startup類的Configure方法中增加v2 json路徑

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/V1/swagger.json", "API V1");
    c.SwaggerEndpoint("/swagger/V2/swagger.json", "API V2");
});

2、配置分組

給UserInfoController配置V1組

[ApiExplorerSettings(GroupName = "V1")]
public class UserInfoController : Controller

給HomeController配置V2組

[ApiExplorerSettings(GroupName = "V2")]
public class HomeController : Controller

執行：

五、結語

Swagger還有很多好用功能，比如自定義Swagger模板、Swagger開啟許可權驗證等，希望感興趣的道友繼續探索！！！

相關文章