使用Swagger爲ASP.NET Core WebApi生成API文檔

團隊工做中每個項目都能提供一份詳盡的說明文檔的話，自行腦補「這個就叫專業.jpg」。可是利用原本就有限的時間編寫一份讓別人看起來舒服的文檔可不是一份美差。故，不少自動化的文檔生成器便應運而生，這裏簡單介紹一個很受歡迎的API文檔工具Swagger在ASP.NET Core上的應用，其開源在GitHub。

 Swagger能夠爲ASP.NET Core項目生成一份美觀的API文檔，並附帶測試功能的UI界面。從實踐出發，接下來介紹如何將Swagger應用在ASP.NET Core WebApi項目中。首先建立ASP.NET Core WebApi的過程這裏就不在贅述了。使用NuGet爲項目添加「Swashbuckle.AspNetCore」的引用。本文撰寫時「Swashbuckle.AspNetCore」已是5.4.1版本了。

來到Startup.cs文件中的ConfigureServices方法中，向服務容器中註冊Swagger生成器（Swagger generator）從而定義Swagger文檔。具體寫法能夠參考下面的寫法

 1 services.AddSwaggerGen(setup =>
 2 {
 3     setup.SwaggerDoc("DemoApi",        //定義文檔的名稱
 4         new OpenApiInfo
 5         {
 6             Title = "DemoApi",
 7             Version = "v1.0",
 8             Contact = new OpenApiContact { Name = "xuhy", Email = "hyxu0826@gmail.com" },
 9             Description = "Demo Api 的描述信息"
10         });
11 });

這裏定義要生成文檔的名稱，及其一些附加的版本信息，聯繫人信息和描述信息等，這些信息都會在最後建立出的UI界面上有所顯示。

來到Startup.cs文件中的Configure方法，插入swaggerswagger.ui中間件來顯示咱們生成的Swagger界面。

1 // 啓用Swagger中間件
2 app.UseSwagger();
3 // 配置SwaggerUI
4 app.UseSwaggerUI(c =>
5 {
6     c.SwaggerEndpoint("/swagger/DemoApi/swagger.json", "DemoApi項目文檔");
7     c.RoutePrefix = string.Empty;
8 
9 });

 到目前爲止，最簡單的Swagger配置便已經完成了。值得注意的一點是，咱們在開發WebApi項目時，須要顯式的爲Action指定Http方法和參數的來源，不然將會都被默認描述成FromQuery。

接下來測試下是否可以正常顯示，運行項目打開瀏覽器，若是不出意外即可以看到相似下面的界面。在其中咱們能夠看到項目中定義的全部Controller和Action。自定義標題及版本信息也都一一呈現，以下圖。而且在controller的下方，還有一個Schemas模塊。在Swashbuckle 的5.0版本後，即可以在Schemas中看到API暴露出來的全部數據類型的具體信息。

 針對Schemas，是基於Newtonsoft 的json序列化器生成的，若是咱們ASP.NET Core項目中所用的Json序列化器是默認的System.Text.Json，則就須要爲此增長一些配置了。首先利用Nuget添加「Swashbuckle.AspNetCore.Newtonsoft」，並在 services.AddSwaggerGen 方法以後添加 services.AddSwaggerGenNewtonsoftSupport(); 

在項目的開發過程當中，對方法、參數和屬性添加完備的註釋信息是一個好習慣，Swagger也支持將這些註釋信息顯示到適當的位置從而更好的起到文檔的用途。

首先咱們須要對AspNetCore項目進行設置，使其生成XML文檔文件。簡單的設置方法是在項目上右鍵→屬性→生成，將其中的「XML文檔文件」勾選上。可是勾選上以後，項目中全部未進行註釋的方法都會報出警告信息，有強迫症的同窗確定不能忍。這時只須要在勾選「XML文檔文件」的同時，爲「取消顯示警告」中添加「1591」，即可以取消這些警告了。

設置好以後來帶註冊Swagger生成器的 AddSwaggerGen 方法中，指定的xml文件的路徑並添加進去便可。

1 //在界面中顯示項目中的註釋
2 var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
3 var commentsFileNameMain = typeof(Program).Assembly.GetName().Name + ".XML";
4 setup.IncludeXmlComments(Path.Combine(basePath, commentsFileNameMain));
5 setup.DocInclusionPredicate((docName, description) => true);

接下來從新編譯啓動項目，即可以看到項目中的註釋信息了。

爲了達到更多自定義的需求，Swagger爲咱們提供了3種過濾器（Operation Filter，Schema Filter，Document Filter）來分別過濾不一樣的部分。舉個例子，有些狀況下，Action的方法參數是一個「複雜」類型，可是咱們不但願將請求參數中的全部屬性都暴露出來，只想暴露實際須要的屬性到文檔中。

首先建立一個自定義的特性，用來標註咱們不想在文檔中暴露的屬性。

1 [AttributeUsage(AttributeTargets.Property)]
2 public class SwaggerExcludeAttribute : Attribute
3 {
4 }

接下來建立過濾器。

 1 public class SwaggerExcludePropFilter : IOperationFilter
 2 {
 3     public void Apply(OpenApiOperation operation, OperationFilterContext context)
 4     {
 5         if (context.MethodInfo.DeclaringType == null) return;
 6         var parms = context.MethodInfo.GetParameters();
 7         foreach (var parameterInfo in parms)
 8         {
 9             foreach (var property in parameterInfo.ParameterType.GetProperties())
10             {
11                 var excludeAttributes = property.GetCustomAttribute<SwaggerExcludeAttribute>();
12                 if (excludeAttributes == null) continue;
13                 var prop = operation.Parameters.FirstOrDefault(p => p.Name == property.Name);
14                 if (prop != null)
15                 {
16                     operation.Parameters.Remove(prop);
17                 }
18             }
19         }
20     }
21 }

注意別忘了在註冊Swagger生成器時將過濾器添加上。

1 //註冊過濾器
2 setup.OperationFilter<SwaggerExcludePropFilter>();

若是此時咱們將 EmployeeQueryDto 的 Gender 屬性標註上 [SwaggerExclude] 特性，從新編譯後運行，屬性消失了。

最後，Swagger中還包含更多高級的用法，具體能夠參考GitHub。