編輯于 2020/04/02

Jwt Bearer權(quán)限認(rèn)證+Swagger 第二篇 已經(jīng)完成了！
在. net core 3.1 WebApi中使用Swagger框架+Jwt權(quán)限驗(yàn)證 第二篇

前言

編輯API接口文檔對(duì)任何一個(gè)開發(fā)人員來說都算是比較重復(fù)，又無聊的工作，所以，需要一種快速有效的方法來構(gòu)建api說明文檔并且具備一定的擴(kuò)展能力。Swagger就具備這些能力，現(xiàn)在Swagger可以說是當(dāng)下最受歡迎的生成REST APIs風(fēng)格文檔工具。
書寫API文檔的工具有很多，但是能稱之為“框架”的，估計(jì)也只有swagger了。

一. 創(chuàng)建工程

創(chuàng)建 asp. net core WebAPI 3.1項(xiàng)目，這里就不過多演示了。

二. 安裝Nuget包依賴

在Nuget包中搜索Swashbuckle.AspNetCore安裝

博主當(dāng)前安裝的版本是5.2.1

Nuget包

三. 配置服務(wù)

Startup.cs 中 ConfigureServices方法

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    #region Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v0.1.0",
            Title = "Blog.Core API",
            Description = "API文檔",
            TermsOfService = new Uri("http://www.itdecent.cn/u/1117a3ecacbc"),
            Contact = new OpenApiContact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = new Uri("http://www.itdecent.cn/u/1117a3ecacbc") }
        });
    });
    #endregion
}

Startup.cs 中 Configure方法

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    #region Swagger
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");

        //直接在根域名訪問(localhost:8001/index.html)
        //c.RoutePrefix = "";

    });
    #endregion

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

三. 運(yùn)行

啟動(dòng)程序后，在Url后面添加Swagger即可訪問Swagger

Url

這樣，Swagger就搭建完成了，馬上F5運(yùn)行看看！是不是非常簡(jiǎn)單，運(yùn)行結(jié)果如下。

Swagger

點(diǎn)擊方法內(nèi)的Try it out，再點(diǎn)擊Execute，就完成了一次接口調(diào)用，是不是非常方便。

四. 接口方法顯示注釋

當(dāng)接口非常多的時(shí)候，那么就需要在接口上顯示中文注釋，這樣也方便前端在調(diào)用接口是方便理解。

1. 右鍵單擊WebApi項(xiàng)目--屬性--生成--輸出

WebApi項(xiàng)目設(shè)置

2. 修改Startup.cs 中 ConfigureServices方法

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    #region Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v0.1.0",
            Title = "Blog.Core API",
            Description = "API文檔",
            TermsOfService = new Uri("http://www.itdecent.cn/u/1117a3ecacbc"),
            Contact = new OpenApiContact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = new Uri("http://www.itdecent.cn/u/1117a3ecacbc") }
        });

        var basePath = AppContext.BaseDirectory;
        var xmlPath = Path.Combine(basePath, "NetCore.Blogs.Swagger.xml");//這個(gè)就是剛剛配置的xml文件名
        c.IncludeXmlComments(xmlPath, true);
    });

    #endregion
}

3. 在Controller的方法中進(jìn)行注釋

注釋方法

當(dāng)然也可以注釋Controller

注釋控制器

運(yùn)行查看效果

顯示效果

五. 忽略CS1591警告

編譯后發(fā)現(xiàn)一大堆的CS1591警告，雖然不會(huì)造成程序的影響，但是強(qiáng)迫癥患者看著難受。
忽略警告非常簡(jiǎn)單，只需要在
WebApi項(xiàng)目--屬性--生成下

忽略警告設(shè)置

六. 設(shè)置swagger頁面為首頁

雖然可以通過輸入/swagger進(jìn)行訪問swagger，但是這樣還是不是很方便的。

1. 打開WebAPI項(xiàng)目下的launchsettings.json文件

Settings

2. 設(shè)置 launchUrl為swagger

launchUrl

再次啟動(dòng)，就會(huì)發(fā)現(xiàn)直接啟定到Swagger頁面了，是不是很方便。

七. 源碼

碼云