[[399419]]

本文轉(zhuǎn)載自微信公眾號(hào)「鵬祥」，作者AZRNG。轉(zhuǎn)載本文請(qǐng)聯(lián)系鵬祥公眾號(hào)。

介紹

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。日?？梢杂糜诤蠖碎_(kāi)發(fā)人員測(cè)試接口或者前后端聯(lián)調(diào)使用。從.net5開(kāi)始，swagger已經(jīng)集成到vs2019編譯器中，可以通過(guò)勾對(duì)選項(xiàng)“啟用OpenAPI支持”顯示基本的swagger配置。

本文示例環(huán)境：vs2019、net5

1 基本使用

新建一個(gè)NetCore API項(xiàng)目，為了測(cè)試效果，我多創(chuàng)建幾個(gè)控制器

image.png

1.1 安裝組件

<ItemGroup> 
   <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" /> 
 </ItemGroup> 

1.2 注冊(cè)swagger服務(wù)

在ConfigureServices中

public void ConfigureServices(IServiceCollection services) 
{ 
    services.AddControllers(); 
    services.AddSwaggerGen(c => 
    { 
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi", Version = "v1" }); 
    }); 
} 

注意：

//netcore3.0之前版本用法

c.SwaggerDoc("v1", new Info { Title = "WebApi", Version = "v1" });

1.3 使用Swagger

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) 
{ 
    if (env.IsDevelopment()) 
    { 
        app.UseDeveloperExceptionPage(); 
        app.UseSwagger(); 
        app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi v1")); 
    } 
 
    app.UseRouting(); 
 
    app.UseAuthorization(); 
 
    app.UseEndpoints(endpoints => 
    { 
        endpoints.MapControllers(); 
    }); 
} 

該示例代碼配置的swagger只在Development環(huán)境下顯示，可以根據(jù)實(shí)際情況來(lái)修改

1.4 啟動(dòng)

運(yùn)行項(xiàng)目，展示下面的效果

image.png

如果這是你寫(xiě)的接口，這個(gè)時(shí)候你的其他同事去看，真的會(huì)一臉懵逼，你這寫(xiě)的都是啥玩意，那么我們來(lái)給這加上注釋吧。

/// <summary> 
/// 用戶(hù)控制器 
/// </summary> 
[Route("api/[controller]")] 
[ApiController] 
public class UserController : ControllerBase 
{ 
    /// <summary> 
    ///查詢(xún)用戶(hù)列表 
    /// </summary> 
    /// <returns></returns> 
    [HttpGet] 
    public IEnumerable<string> Get() 
    { 
        return new string[] { "value1", "value2" }; 
    } 
 
    /// <summary> 
    /// 查詢(xún)用戶(hù)詳情 
    /// </summary> 
    /// <param name="id"></param> 
    /// <returns></returns> 
    [HttpGet("{id}")] 
    public string Get(int id) 
    { 
        return "value"; 
    } 
 
    /// <summary> 
    /// 刪除用戶(hù) 
    /// </summary> 
    /// <param name="id"></param> 
    [HttpDelete("{id}")] 
    public void Delete(int id) 
    { 
    } 
} 

這樣子加了注釋還不行，swagger還讀取不到我們的注釋?zhuān)覀冞€需要生成xml文檔并且讓swagger使用，選中項(xiàng)目右鍵屬性=>生成=>xml文檔文件

image.png

修改注入swagger配置

services.AddSwaggerGen(c => 
   { 
       c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi", Version = "v1" }); 
 
       // 使用反射獲取xml文件。并構(gòu)造出文件的路徑 
       var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; 
       var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 
       // 啟用xml注釋.第二個(gè)參數(shù)啟用控制器的注釋?zhuān)J(rèn)為false. 
       c.IncludeXmlComments(xmlPath, true); 
   }); 

再次啟動(dòng)項(xiàng)目查看界面

image.png

至此，基礎(chǔ)的配置swagger顯示注釋已經(jīng)實(shí)現(xiàn)了，那么如何調(diào)用我們接口那?

image.png

通過(guò)該界面，我們可以看到請(qǐng)求地址、請(qǐng)求方式、入?yún)㈩?lèi)型、輸出參數(shù)等。

注：

通過(guò)設(shè)置取消顯示警告：1591 ， 可以去除方法和類(lèi)上面的xml注釋警告

如果實(shí)體類(lèi)不在當(dāng)前程序集下，需要同樣方式配置實(shí)體類(lèi)程序集的xml文檔到swagger配置

2. swagger傳遞JWT

jwt是一個(gè)基于json的、用于在網(wǎng)絡(luò)上聲明某種主張的令牌，通常是用三部分組成：頭信息，消息體，簽名。他是一種雙方之間傳遞安全信息的表述性聲明規(guī)范?？梢宰鰴?quán)限驗(yàn)證的工具，但是目的不是為了數(shù)據(jù)加密和保護(hù)。雖然看似像是加密的數(shù)據(jù)，但是它并沒(méi)有加密，不適合存儲(chǔ)機(jī)密信息。

如果我們接口是需要傳遞token才可以訪問(wèn)，那么我們就需要對(duì)我們的swagger配置再進(jìn)行改造

services.AddSwaggerGen(c => 
            { 
                c.SwaggerDoc("v1", new OpenApiInfo {Title = "WebApi", Version = "v1"}); 
 
                // 使用反射獲取xml文件。并構(gòu)造出文件的路徑 
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; 
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 
                // 啟用xml注釋.第二個(gè)參數(shù)啟用控制器的注釋?zhuān)J(rèn)為false. 
                c.IncludeXmlComments(xmlPath, true); 
 
                var security = new Dictionary<string, IEnumerable<string>> {{"Bearer", new string[] { }}}; 
                c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme() 
                { 
                    Description = "JWT授權(quán)(數(shù)據(jù)將在請(qǐng)求頭中進(jìn)行傳輸) 在下方輸入Bearer {token} 即可，注意兩者之間有空格", 
                    Name = "Authorization", //jwt默認(rèn)的參數(shù)名稱(chēng) 
                    In = ParameterLocation.Header, //jwt默認(rèn)存放Authorization信息的位置(請(qǐng)求頭中) 
                    Type = SecuritySchemeType.ApiKey, 
                }); 
                c.AddSecurityRequirement(new OpenApiSecurityRequirement 
                { 
                    { 
                        new OpenApiSecurityScheme 
                        { 
                            Reference = new OpenApiReference() 
                            { 
                                Id = "Bearer", 
                                Type = ReferenceType.SecurityScheme 
                            } 
                        }, 
                        Array.Empty<string>() 
                    } 
                }); 
            }); 

運(yùn)行，查看界面，發(fā)現(xiàn)界面有所不同

image.png

雖然我手上沒(méi)有token，但是我也沒(méi)有寫(xiě)校驗(yàn)token的代碼，所以我們就暫且看為一個(gè)頭部傳遞的工具使用。jwt具體使用后續(xù)再講。

token傳遞方式就是在Headers增加 Authorization:Bearer {token} ，然后需要在程序中配置校驗(yàn)token，當(dāng)下我們只是模擬swagger在header中傳遞值。

在輸入框輸出：Bearer AABBCC

在Action中獲取我們傳輸?shù)臄?shù)據(jù)

var token = HttpContext.Request.Headers["Authorization"]; 

image.png

3 參考文檔

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-5.0