.NetCore WebApi——Swagger簡單配置

時間 2019-11-12

標籤 netcore webapi swagger 簡單配置简体版

原文原文鏈接

在先後端分離的大環境下，API接口文檔成爲了先後端交流的一個重點。Swagger讓開發人員擺脫了寫接口文檔的痛苦。html

官方網址：https://swagger.io/前端

在.Net Core WebApi中經過簡單配置便可使用這一強大的功能。ios

目錄：git

.NetCore WebApi——Swagger簡單配置github

.NetCore WebApi——基於JWT的簡單身份認證與受權（Swagger）json

.NetCore WebApi —— Swagger版本控制後端

1.新建一個API的項目架構

選擇 API 項目app

2.引入Swagger包。.Net Core 中支持兩個分別爲Swashbuckle和NSwag。二者的配置大同小異。這裏以Swashbuckle爲例。前後端分離

方式1：選擇工具——Nuget包管理——管理解決方案的Nuget包

搜索：Swashbuckle.AspNetCore 安裝便可

方式2：直接在程序包管理控制檯輸入：Install-Package Swashbuckle.AspNetCore 回車便可安裝

安裝以後在項目的Nuget包中就能夠看到了

3.配置Swagger中間件

3.1 在Startup類ConfigureServices方法中添加Swagger服務並配置文檔信息

 public void ConfigureServices(IServiceCollection services)
        {
            // 註冊Swagger服務
            services.AddSwaggerGen(c =>
            {
                // 添加文檔信息
                c.SwaggerDoc("v1", new Info { Title = "CoreWebApi", Version = "v1" });
            });
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
        }

3.2 在 Startup類Configure 方法中，啓用中間件爲生成的 JSON 文檔和 Swagger UI 提供服務

 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }
      
            app.UseHttpsRedirection();
            // 啓用Swagger中間件
            app.UseSwagger();

            // 配置SwaggerUI
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");
               
            });
            app.UseMvc();
        }

右鍵項目屬性，將URL地址固定到某個端口

而後將啓動項設置爲當前項目，而後啓動。

在根目錄目前是沒有東西的。下一步將在根目錄處使用SwaggerUI

將RoutePrefix屬性設置爲空

    app.UseHttpsRedirection();
            // 啓用Swagger中間件
            app.UseSwagger();

            // 配置SwaggerUI
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");
                c.RoutePrefix = string.Empty;
            });

再次啓動項目，SwaggerUI文檔成功顯示出來。總體簡潔大方。

API的信息說明：傳遞給AddSwaggerGen（）的方法可配置一些API的信息說明以及做者信息等，來展現到UI頁面。修改AddSwaggerGen（）方法。

// 註冊Swagger服務
            services.AddSwaggerGen(c =>
            {
                // 添加文檔信息
                c.SwaggerDoc("v1", new Info
                {
                    Title = "CoreWebApi",
                    Version = "v1",
                    Description="ASP.NET CORE WebApi",
                    Contact=new Contact
                    {
                        Name="Jee",
                        Email="princess@gmail.com"
                    }
                });
            });

展現對應的信息

4.啓用XML註釋。上邊的效果只有一個簡單說明，並無咱們在後臺寫的註釋。啓用XML註釋以後能夠輕鬆映射到UI界面方便前端開發人員理解。

右鍵當前項目——編輯****.csproj 的文件在PropertyGroup標籤組中添加以下兩條

<GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn>

這兩句的大概意思就是啓用XML註釋，並忽略未寫註釋的警告。不添加1591若是某個方法未寫 "///"各式的註釋，vs會有警示的消息。

以後AddSwaggerGen（）方法中讀取xml文件路徑並啓用

       // 註冊Swagger服務
            services.AddSwaggerGen(c =>
            {
                // 添加文檔信息
                c.SwaggerDoc("v1", new Info
                {
                    Title = "CoreWebApi",
                    Version = "v1",
                    Description="ASP.NET CORE WebApi",
                    Contact=new Contact
                    {
                        Name="Jee",
                        Email="princess@gmail.com"
                    }
                });
                // 使用反射獲取xml文件。並構造出文件的路徑
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 啓用xml註釋. 該方法第二個參數啓用控制器的註釋，默認爲false.
                c.IncludeXmlComments(xmlPath,true);
            });