.NetCore2.1 WebAPI新增Swagger插件

說明

Swagger是一個WebAPI線上註解、調試插件，過去我們主要通過手工撰寫WebAPI介面的交互文檔供前端開發人員或外部開發者，

官網地址：https://swagger.io/。

但是在實際工作中，往往咋們的文檔工作通常落後於實際的環境，導致文檔和實際介面不一致，前後端開發人員苦不堪言。

Swagger的出現解放了介面文檔撰寫的麻煩也提高了前後端開發者的工作效率，所謂“工欲善其事,必先利其器 ”。現在讓咋們

瞭解下在.NET Core 2.1下如何實現Swagger。

1、Nuget安裝依賴包

 首先Nuget安裝Swashbuckle.AspNetCore

打開Nuget控制台(程式包管理控制台)，鍵入下列命令

Install-Package  Swashbuckle.AspNetCore

2、添加Swagger中間件

public IServiceProvider ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });

            services.AddMvc().AddJsonOptions(options =>
            {
                //忽略迴圈引用
                options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;
                //不使用駝峰樣式的key
                options.SerializerSettings.ContractResolver = new DefaultContractResolver();
            })
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            // Register the Swagger generator, defining 1 or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
            });
            return RegisterAutofac(services);//註冊Autofac
        }

 引用Swashbuckle.AspNetCore.Swagger，並啟用中間件

 1    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
 2         {
 3             if (env.IsDevelopment())
 4             {
 5                 app.UseDeveloperExceptionPage();
 6             }
 7             // Enable middleware to serve generated Swagger as a JSON endpoint.
 8             app.UseSwagger();
 9             // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
10             // specifying the Swagger JSON endpoint.
11             app.UseSwaggerUI(c =>
12             {
13                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
14             });
15             app.UseVisitLogger();
16             app.UseMvc();
17         }

3、配置WebAPI項目屬性

1、雙擊Properties下的launchSettings.json，將launchUrl更新為swagger

F5結果如下：

 4、新增註解

如上圖，雖然WebAPI已經出來了，但是呢，並沒有發現我們在Action上寫的註釋? 老司機應該知道在Framework版本里我們需要

將WebAPI啟動項屬性里更改“項目生產“一欄中新增XML文檔，.NetCore也是如此。如下圖:

 保存後，按F5發現並木有生產註解，Why???  那是因為我們必須明確告訴Swagger應該從哪個路徑讀取WebAPI註解XML文件，更新Startup下的ConfigureServices。

參考下麵代碼:

           // Register the Swagger generator, defining 1 or more Swagger documents
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info { Title = "TestSystem", Version = "v1" });                
                //註入WebAPI註釋文件給Swagger      
                var xmlPath = Path.Combine(AppContext.BaseDirectory, "AirWebApi.xml");
                options.IncludeXmlComments(xmlPath);

                options.IgnoreObsoleteActions();
                ////options.IgnoreObsoleteControllers();
                //// 類、方法標記 [Obsolete]，可以阻止【Swagger文檔】生成
                options.DescribeAllEnumsAsStrings();             
                options.OperationFilter<FormDataOperationFilter>();
            });

代碼不單單新增了註解，同時添加了阻止Swagger文檔生成的配置，通過讀取系統的[Obsolete]特性實現。

現在，讓我們再看看結果吧~

 是不是很爽~~

還有，Swagger是支持授權登錄的哦，這個待研究。