快捷導(dǎo)航

.Net Core2.1 WebAPI新增Swagger插件詳解

更新時(shí)間：2018年07月10日 11:34:42 作者：Bug帝

這篇文章主要給大家介紹了關(guān)于.Net Core2.1 WebAPI新增Swagger插件的相關(guān)資料，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧

說明

Swagger是一個(gè)WebAPI在線注解、調(diào)試插件，過去我們主要通過手工撰寫WebAPI接口的交互文檔供前端開發(fā)人員或外部開發(fā)者，

官網(wǎng)地址：https://swagger.io/。

但是在實(shí)際工作中，往往咋們的文檔工作通常落后于實(shí)際的環(huán)境，導(dǎo)致文檔和實(shí)際接口不一致，前后端開發(fā)人員苦不堪言。

Swagger的出現(xiàn)解放了接口文檔撰寫的麻煩也提高了前后端開發(fā)者的工作效率，所謂“工欲善其事,必先利其器 ”?，F(xiàn)在讓咋們

了解下在.NET Core 2.1下如何實(shí)現(xiàn)Swagger。

1、Nuget安裝依賴包

首先Nuget安裝Swashbuckle.AspNetCore

打開Nuget控制臺(tái)(程序包管理控制臺(tái))，鍵入下列命令

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 =>
  {
  //忽略循環(huán)引用
  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，并啟用中間件

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
 {
  if (env.IsDevelopment())
  {
  app.UseDeveloperExceptionPage();
  }
  // Enable middleware to serve generated Swagger as a JSON endpoint.
  app.UseSwagger();
  // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
  // specifying the Swagger JSON endpoint.
  app.UseSwaggerUI(c =>
  {
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
  });
  app.UseVisitLogger();
  app.UseMvc();
 }

3、配置WebAPI項(xiàng)目屬性

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

F5結(jié)果如下：

4、新增注解

如上圖，雖然WebAPI已經(jīng)出來了，但是呢，并沒有發(fā)現(xiàn)我們在Action上寫的注釋? 老司機(jī)應(yīng)該知道在Framework版本里我們需要

將WebAPI啟動(dòng)項(xiàng)屬性里更改“項(xiàng)目生產(chǎn)“一欄中新增XML文檔，.NetCore也是如此。如下圖:

保存后，按F5發(fā)現(xiàn)并木有生產(chǎn)注解，Why??? 那是因?yàn)槲覀儽仨毭鞔_告訴Swagger應(yīng)該從哪個(gè)路徑讀取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();
  //// 類、方法標(biāo)記 [Obsolete]，可以阻止【Swagger文檔】生成
  options.DescribeAllEnumsAsStrings();   
  options.OperationFilter<FormDataOperationFilter>();
 });

代碼不單單新增了注解，同時(shí)添加了阻止Swagger文檔生成的配置，通過讀取系統(tǒng)的[Obsolete]特性實(shí)現(xiàn)。

現(xiàn)在，讓我們再看看結(jié)果吧~