快捷導(dǎo)航

.NET中的Swagger使用示例詳解

更新時(shí)間：2023年12月25日 15:49:40 作者：我是一只小小魚(yú)~

Swagger?(OpenAPI)?是一個(gè)與語(yǔ)言無(wú)關(guān)的規(guī)范,用于描述?REST?API,這篇文章給大家介紹.NET中的Swagger使用,感興趣的朋友一起看看吧

前言

現(xiàn)在很多項(xiàng)目都是前后端分離的項(xiàng)目，后端寫(xiě)好接口跟前端對(duì)接，需要后端提供接口文檔、參數(shù)等注釋，這上面花時(shí)間著這些東西，接口修改又要去修改文檔，很不方便前后端人員開(kāi)發(fā)

一、Swagger是什么？

Swagger (OpenAPI) 是一個(gè)與語(yǔ)言無(wú)關(guān)的規(guī)范，用于描述 REST API。

OpenAPI 與 Swagger關(guān)系
Swagger 項(xiàng)目已于 2015 年捐贈(zèng)給 OpenAPI 計(jì)劃，自此它被稱為 OpenAPI，這兩個(gè)名稱可互換使用。不過(guò)，“OpenAPI”指的是規(guī)范。
簡(jiǎn)而言之：
OpenAPI 是一種規(guī)范。
Swagger 是一種使用 OpenAPI 規(guī)范的工具。例如，OpenAPIGenerator 和 SwaggerUI。

目前從NETCore從3.1起已經(jīng)集成Sawwger,無(wú)需再去引用庫(kù)，創(chuàng)建項(xiàng)目后運(yùn)行API項(xiàng)目自動(dòng)Sawwger接口文檔的頁(yè)面

介紹大家可能會(huì)關(guān)注的一些點(diǎn)

二、如何Swagger文檔說(shuō)明的信息

1.在AddSwaggerGen方法中寫(xiě)入文檔信息

代碼如下（示例）：

builder.Services.AddSwaggerGen(options =>
{
    //諸如作者、文檔說(shuō)明的信息
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "我的API",
        Description = "這是我的netcoreAPI項(xiàng)目",//描述信息
        Contact = new OpenApiContact
        {
            Name = "我是小小魚(yú)",
            Url = new Uri("https://blog.csdn.net/qq_42335551")
        }
    });

2.運(yùn)行效果

如圖（示例）：

二、文檔UI界面標(biāo)題、路由設(shè)置

如何修改標(biāo)簽頁(yè)的名、和地址要怎么修改呢

1.在中間件UseSwaggerUI方法中配置

 app.UseSwagger();
    app.UseSwaggerUI(c => { 
        c.DocumentTitle = "后臺(tái)接口列表";   //標(biāo)簽頁(yè)標(biāo)題
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "公共模塊");//接口文檔json文件
        c.RoutePrefix =string.Empty;// 注:這里的路由修改后，launchSettings.json中的launchUrl對(duì)應(yīng)需要調(diào)整為""
    });

在次啟動(dòng)項(xiàng)目已經(jīng)變成修改后的標(biāo)簽頁(yè)和地址

三、文檔UI界面添加接口注釋

如何添加接口的注釋呢

1.在 .csproj中配置

在解決方案資源管理器中右鍵單擊該項(xiàng)目。
將 GenerateDocumentationFile 添加到 .csproj 文件中PropertyGroup節(jié)點(diǎn)下

<GenerateDocumentationFile>true</GenerateDocumentationFile>

2.在AddSwaggerGen方法中配置IncludeXmlComments

代碼如下（示例）：

builder.Services.AddSwaggerGen(options =>
{
    //諸如作者、文檔說(shuō)明的信息
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "我的API",
        Description = "這是我的netcoreAPI項(xiàng)目",//描述信息
        Contact = new OpenApiContact
        {
            Name = "我是小小魚(yú)",
            Url = new Uri("https://blog.csdn.net/qq_42335551")
        }
    });
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), true);//true 顯示控制器注釋
});

運(yùn)行效果，已經(jīng)顯示出我們的注釋

可以在控制器、參數(shù)、實(shí)體類增加注釋后，再次運(yùn)行都有顯示

四、對(duì)接口進(jìn)行分組

1.在AddSwaggerGen、UseSwaggerUI分別添加如下信息

例如

    options.SwaggerDoc("yw", new OpenApiInfo { Title = "業(yè)務(wù)模塊", Version = "yw" });
    options.SwaggerDoc("qt", new OpenApiInfo { Title = "其他模塊", Version = "qt" });

例如

 c.SwaggerEndpoint("/swagger/v1/swagger.json", "公共模塊");//接口文檔json文件
 c.SwaggerEndpoint("/swagger/yw/swagger.json", "業(yè)務(wù)模塊");
 c.SwaggerEndpoint("/swagger/qt/swagger.json", "其他模塊");
 c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);//接口不展開(kāi)None