C#項目中引用Swagger的詳細步驟和配置方式

更新時間：2025年02月27日 10:52:02 作者：太陽

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

安裝Swagger相關包

打開你的C#項目解決方案，在Visual Studio中，右鍵點擊項目名稱，選擇“管理NuGet程序包”。

在NuGet包管理器中，搜索以下包并進行安裝：

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

配置Swagger服務

在項目的Startup.cs文件中，找到ConfigureServices方法，在其中添加以下代碼來配置Swagger服務：

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

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

    // 添加Swagger生成器服務
    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有身份驗證等安全機制，可以在這里配置
        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[] {}
            }
        });
    });
}

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

啟用Swagger中間件

在Startup.cs文件的Configure方法中，添加以下代碼來啟用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的其他選項，如文檔展開深度等
        c.DocExpansion(DocExpansion.None);
    });
}

這段代碼首先使用UseSwagger中間件來生成Swagger JSON文檔，然后使用UseSwaggerUI中間件來提供Swagger UI界面，方便用戶查看和測試API。通過SwaggerEndpoint方法指定了Swagger JSON文檔的路由和顯示在Swagger UI中的文檔名稱。

驗證Swagger是否配置成功

運行你的C#項目，在瀏覽器中輸入http://localhost:port/swagger，其中port是你的項目運行的端口號。
如果一切配置正確，你應該能夠看到Swagger UI界面，其中列出了你項目中的所有API端點，并且可以查看每個端點的詳細信息和進行測試。

對特定API添加注釋和描述

為了使Swagger文檔更加詳細和準確，可以在控制器的方法和模型類上添加XML注釋。
例如：

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

這樣，在Swagger UI中就可以看到更詳細的API說明信息。

在配置Swagger服務時，添加安全定義可以讓你為API指定各種安全機制，如JWT認證、API密鑰認證等。以下以常見的JWT認證和API密鑰認證為例，介紹如何添加安全定義：

JWT認證安全定義

添加命名空間引用

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

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

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

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

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

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

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

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

API密鑰認證安全定義

添加命名空間引用

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

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

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

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

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

    // 添加API密鑰安全定義
    c.AddSecurityDefinition("ApiKey", new OpenApiSecurityScheme
    {
        // 定義安全機制的類型為API密鑰
        Type = SecuritySchemeType.ApiKey,
        // 說明該密鑰位于請求頭中
        In = ParameterLocation.Header,
        // 請求頭中用于傳遞API密鑰的字段名稱
        Name = "X-Api-Key",
        // 對該安全定義的描述，在Swagger UI中會顯示給用戶
        Description = "請輸入你的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的安全定義，指定安全機制為API密鑰，位于請求頭的X - Api - Key字段中，并給出了描述。同時也添加了安全要求，確保使用ApiKey安全定義的API在調(diào)用時需要提供有效的API密鑰。

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

準備工作

確保已在項目中成功引用并配置了Swagger，且項目能夠正常運行，Swagger UI可以正常訪問。

測試API

訪問Swagger UI：啟動項目后，在瀏覽器中輸入Swagger UI的地址，如http://localhost:port/swagger，其中port是項目運行的端口號。進入Swagger UI界面，會看到項目中所有暴露的API列表，每個API以其定義的HTTP方法（如GET、POST、PUT、DELETE等）和路徑顯示。

選擇要測試的API：在Swagger UI中找到想要測試的API端點。每個API端點都有對應的描述和參數(shù)信息。

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

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

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

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

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

調(diào)試API

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