快捷導(dǎo)航

C#項(xiàng)目中引用Swagger的詳細(xì)步驟和配置方式

更新時(shí)間：2025年02月27日 10:52:02 作者：太陽(yáng)

本文詳細(xì)介紹了如何在C#項(xiàng)目中安裝和配置Swagger,包括添加相關(guān)NuGet包、配置Swagger服務(wù)和啟用Swagger中間件,還講解了如何為API添加注釋和描述,配置安全定義,以及如何使用Swagger進(jìn)行API測(cè)試和調(diào)試

安裝Swagger相關(guān)包

打開(kāi)你的C#項(xiàng)目解決方案，在Visual Studio中，右鍵點(diǎn)擊項(xiàng)目名稱(chēng)，選擇“管理NuGet程序包”。

在NuGet包管理器中，搜索以下包并進(jìn)行安裝：

Swashbuckle.AspNetCore：這是Swagger用于ASP.NET Core的主要庫(kù)，它包含了生成Swagger文檔和提供Swagger UI的功能。
Microsoft.OpenApi.Models：提供了OpenAPI規(guī)范的模型定義，Swashbuckle.AspNetCore會(huì)使用這些模型來(lái)生成Swagger文檔。

配置Swagger服務(wù)

在項(xiàng)目的Startup.cs文件中，找到ConfigureServices方法，在其中添加以下代碼來(lái)配置Swagger服務(wù)：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public void ConfigureServices(IServiceCollection services)
{
    // 其他服務(wù)配置...

    // 添加Swagger生成器服務(wù)
    services.AddSwaggerGen(c =>
    {
        // 定義Swagger文檔信息
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "Your API Title",
            Description = "Your API description",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Contact Name",
                Email = "contact@example.com",
                Url = new Uri("https://example.com/contact")
            },
            License = new OpenApiLicense
            {
                Name = "License Name",
                Url = new Uri("https://example.com/license")
            }
        });

        // 配置XML注釋文件路徑，以便在Swagger文檔中顯示方法注釋等信息
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);

        // 如果你的API有身份驗(yàn)證等安全機(jī)制，可以在這里配置
        c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
        {
            In = ParameterLocation.Header,
            Description = "Please enter JWT with Bearer prefix",
            Name = "Authorization",
            Type = SecuritySchemeType.ApiKey
        });
        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                },
                new string[] {}
            }
        });
    });
}

上述代碼中，首先通過(guò)AddSwaggerGen方法添加了Swagger生成器服務(wù)，并定義了Swagger文檔的基本信息，如版本、標(biāo)題、描述等。然后配置了XML注釋文件的路徑，這樣Swagger會(huì)根據(jù)XML注釋生成更詳細(xì)的文檔內(nèi)容。最后，配置了Bearer令牌的身份驗(yàn)證機(jī)制。

啟用Swagger中間件

在Startup.cs文件的Configure方法中，添加以下代碼來(lái)啟用Swagger中間件：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 其他中間件配置...

    // 啟用Swagger
    app.UseSwagger();

    // 啟用Swagger UI，指定Swagger JSON文檔的路由
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API v1");
        // 如果需要，可以配置Swagger UI的其他選項(xiàng)，如文檔展開(kāi)深度等
        c.DocExpansion(DocExpansion.None);
    });
}

這段代碼首先使用UseSwagger中間件來(lái)生成Swagger JSON文檔，然后使用UseSwaggerUI中間件來(lái)提供Swagger UI界面，方便用戶(hù)查看和測(cè)試API。通過(guò)SwaggerEndpoint方法指定了Swagger JSON文檔的路由和顯示在Swagger UI中的文檔名稱(chēng)。

驗(yàn)證Swagger是否配置成功

運(yùn)行你的C#項(xiàng)目，在瀏覽器中輸入http://localhost:port/swagger，其中port是你的項(xiàng)目運(yùn)行的端口號(hào)。
如果一切配置正確，你應(yīng)該能夠看到Swagger UI界面，其中列出了你項(xiàng)目中的所有API端點(diǎn)，并且可以查看每個(gè)端點(diǎn)的詳細(xì)信息和進(jìn)行測(cè)試。

對(duì)特定API添加注釋和描述

為了使Swagger文檔更加詳細(xì)和準(zhǔn)確，可以在控制器的方法和模型類(lèi)上添加X(jué)ML注釋。
例如：

/// <summary>
/// 獲取用戶(hù)信息
/// </summary>
/// <param name="id">用戶(hù)ID</param>
/// <returns>用戶(hù)信息對(duì)象</returns>
[HttpGet("{id}")]
public IActionResult GetUser(int id)
{
    // 方法實(shí)現(xiàn)
}

這樣，在Swagger UI中就可以看到更詳細(xì)的API說(shuō)明信息。

在配置Swagger服務(wù)時(shí)，添加安全定義可以讓你為API指定各種安全機(jī)制，如JWT認(rèn)證、API密鑰認(rèn)證等。以下以常見(jiàn)的JWT認(rèn)證和API密鑰認(rèn)證為例，介紹如何添加安全定義：

JWT認(rèn)證安全定義

添加命名空間引用

在Startup.cs文件的頂部，添加以下命名空間引用：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

在ConfigureServices方法中配置Swagger安全定義

在Startup.cs文件的ConfigureServices方法中，找到services.AddSwaggerGen(c => {})代碼塊，在其中添加以下代碼：

// 添加Swagger生成器服務(wù)
services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...

    // 添加JWT Bearer安全定義
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        // 定義安全機(jī)制的類(lèi)型為API密鑰
        Type = SecuritySchemeType.ApiKey,
        // 說(shuō)明該密鑰位于請(qǐng)求頭中
        In = ParameterLocation.Header,
        // 請(qǐng)求頭中用于傳遞JWT令牌的字段名稱(chēng)
        Name = "Authorization",
        // 對(duì)該安全定義的描述，在Swagger UI中會(huì)顯示給用戶(hù)
        Description = "請(qǐng)輸入帶有Bearer前綴的JWT令牌"
    });

    // 添加安全要求，指定使用Bearer安全定義的API需要進(jìn)行身份驗(yàn)證
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                // 引用前面定義的Bearer安全定義
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            // 這里可以指定一些額外的作用域或權(quán)限，如果不需要可以留空數(shù)組
            new string[] { }
        }
    });
});

上述代碼首先使用AddSecurityDefinition方法添加了名為Bearer的安全定義，指定了安全機(jī)制為API密鑰，位于請(qǐng)求頭的Authorization字段中，并給出了描述。然后使用AddSecurityRequirement方法指定了使用Bearer安全定義的API需要進(jìn)行身份驗(yàn)證。

API密鑰認(rèn)證安全定義

添加命名空間引用

同樣在Startup.cs文件的頂部，添加與JWT認(rèn)證安全定義時(shí)相同的命名空間引用：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

在ConfigureServices方法中配置Swagger安全定義

在Startup.cs文件的ConfigureServices方法中，找到services.AddSwaggerGen(c => {})代碼塊，在其中添加以下代碼：

// 添加Swagger生成器服務(wù)
services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...

    // 添加API密鑰安全定義
    c.AddSecurityDefinition("ApiKey", new OpenApiSecurityScheme
    {
        // 定義安全機(jī)制的類(lèi)型為API密鑰
        Type = SecuritySchemeType.ApiKey,
        // 說(shuō)明該密鑰位于請(qǐng)求頭中
        In = ParameterLocation.Header,
        // 請(qǐng)求頭中用于傳遞API密鑰的字段名稱(chēng)
        Name = "X-Api-Key",
        // 對(duì)該安全定義的描述，在Swagger UI中會(huì)顯示給用戶(hù)
        Description = "請(qǐng)輸入你的API密鑰"
    });

    // 添加安全要求，指定使用ApiKey安全定義的API需要提供有效的API密鑰
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                // 引用前面定義的ApiKey安全定義
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "ApiKey"
                }
            },
            // 這里可以指定一些額外的作用域或權(quán)限，如果不需要可以留空數(shù)組
            new string[] { }
        }
    });
});

上述代碼添加了名為ApiKey的安全定義，指定安全機(jī)制為API密鑰，位于請(qǐng)求頭的X - Api - Key字段中，并給出了描述。同時(shí)也添加了安全要求，確保使用ApiKey安全定義的API在調(diào)用時(shí)需要提供有效的API密鑰。

在Swagger中可以方便地進(jìn)行API的測(cè)試和調(diào)試，以下是具體步驟：

準(zhǔn)備工作

確保已在項(xiàng)目中成功引用并配置了Swagger，且項(xiàng)目能夠正常運(yùn)行，Swagger UI可以正常訪問(wèn)。

測(cè)試API

訪問(wèn)Swagger UI：?jiǎn)?dòng)項(xiàng)目后，在瀏覽器中輸入Swagger UI的地址，如http://localhost:port/swagger，其中port是項(xiàng)目運(yùn)行的端口號(hào)。進(jìn)入Swagger UI界面，會(huì)看到項(xiàng)目中所有暴露的API列表，每個(gè)API以其定義的HTTP方法（如GET、POST、PUT、DELETE等）和路徑顯示。

選擇要測(cè)試的API：在Swagger UI中找到想要測(cè)試的API端點(diǎn)。每個(gè)API端點(diǎn)都有對(duì)應(yīng)的描述和參數(shù)信息。

填寫(xiě)參數(shù)：對(duì)于需要參數(shù)的API，在Swagger UI提供的參數(shù)輸入?yún)^(qū)域填寫(xiě)相應(yīng)的值。參數(shù)類(lèi)型可能包括路徑參數(shù)、查詢(xún)參數(shù)、請(qǐng)求體參數(shù)等。

路徑參數(shù)：通常在API路徑中以大括號(hào){}表示，直接在對(duì)應(yīng)的輸入框中輸入?yún)?shù)值。
查詢(xún)參數(shù)：一般在路徑后面以問(wèn)號(hào)?開(kāi)始，多個(gè)參數(shù)之間用&連接，在Swagger UI中會(huì)有專(zhuān)門(mén)的輸入框供填寫(xiě)查詢(xún)參數(shù)的名稱(chēng)和值。
請(qǐng)求體參數(shù)：對(duì)于POST、PUT等需要發(fā)送請(qǐng)求體的API，在Swagger UI中通常有一個(gè)專(zhuān)門(mén)的區(qū)域用于輸入JSON或其他格式的請(qǐng)求體數(shù)據(jù)?？梢愿鶕?jù)API的要求構(gòu)造正確的請(qǐng)求體結(jié)構(gòu)，并填入相應(yīng)的值。

設(shè)置請(qǐng)求頭：如果API需要特定的請(qǐng)求頭信息，如Authorization、Content-Type等，在Swagger UI中找到“請(qǐng)求頭”或類(lèi)似的區(qū)域，添加相應(yīng)的請(qǐng)求頭名稱(chēng)和值。例如，如果API需要進(jìn)行身份驗(yàn)證，可能需要在這里添加Authorization頭，并設(shè)置其值為有效的令牌。

執(zhí)行測(cè)試：填寫(xiě)完參數(shù)和請(qǐng)求頭后，點(diǎn)擊API端點(diǎn)旁邊的“執(zhí)行”或“試一下！”按鈕，Swagger將發(fā)送請(qǐng)求到后端API。

查看響應(yīng)結(jié)果：發(fā)送請(qǐng)求后，Swagger UI會(huì)顯示API的響應(yīng)結(jié)果，包括響應(yīng)狀態(tài)碼、響應(yīng)頭和響應(yīng)體。可以根據(jù)響應(yīng)信息判斷API是否正常工作，以及返回的數(shù)據(jù)是否符合預(yù)期。

調(diào)試API

查看請(qǐng)求詳情：如果測(cè)試結(jié)果不符合預(yù)期，可查看請(qǐng)求的詳細(xì)信息來(lái)幫助調(diào)試。在Swagger UI中，通常有一個(gè)“查看請(qǐng)求”或類(lèi)似的按鈕，點(diǎn)擊后可以查看發(fā)送的完整請(qǐng)求信息，包括請(qǐng)求URL、方法、參數(shù)、請(qǐng)求頭和請(qǐng)求體等，確保請(qǐng)求的內(nèi)容與預(yù)期一致。
檢查響應(yīng)狀態(tài)碼：根據(jù)響應(yīng)狀態(tài)碼判斷請(qǐng)求的處理情況。常見(jiàn)的狀態(tài)碼如200表示請(qǐng)求成功，400表示客戶(hù)端請(qǐng)求錯(cuò)誤，401表示未授權(quán)，500表示服務(wù)器內(nèi)部錯(cuò)誤等。根據(jù)不同的狀態(tài)碼，可以初步確定問(wèn)題所在的方向。
分析響應(yīng)體：仔細(xì)查看響應(yīng)體中的信息，可能包含錯(cuò)誤消息、調(diào)試信息或其他有用的提示。如果響應(yīng)體是JSON格式，可以使用JSON格式化工具來(lái)更清晰地查看其結(jié)構(gòu)和內(nèi)容。
結(jié)合后端日志：在調(diào)試API時(shí)，查看后端服務(wù)器的日志是非常有幫助的。后端日志可以提供更詳細(xì)的信息，如請(qǐng)求的處理過(guò)程、出現(xiàn)的異常等。根據(jù)日志中的信息，可以定位到具體的代碼位置，進(jìn)一步分析和解決問(wèn)題。
修改請(qǐng)求并重新測(cè)試：根據(jù)分析的結(jié)果，對(duì)請(qǐng)求參數(shù)、請(qǐng)求頭或請(qǐng)求體進(jìn)行修改，然后再次點(diǎn)擊“執(zhí)行”按鈕，重新發(fā)送請(qǐng)求，觀察響應(yīng)結(jié)果是否有所改善。通過(guò)不斷地修改和測(cè)試，逐步調(diào)試API，直到達(dá)到預(yù)期的效果。