在ASP.NET Core Web API上使用Swagger提供API文檔

我在開發自己的博客系統（http://daxnet.me）時，給自己的RESTful服務增加了基於Swagger的API文檔功能。當設置IISExpress的默認啟動路由到Swagger的API文檔頁面后，在IISExpress啟動Web API站點后，會自動重定向到API文檔頁面，非常方便。這不僅讓我能夠快速省查API設計的合理性，同時從API的使用角度也為我自己提供了便捷。下圖就是我的博客系統RESTful API的Swagger文檔界面：

接下來，讓我們一起看一下如何在ASP.NET Core Web API上實現這一基於Swagger的API文檔頁面。

實現步驟

創建ASP.NET Web API應用程序

這部分內容就不多說了，方法有很多，可以在安裝了Visual Studio 2015/2017 Tools for .NET Core后，使用Visual Studio 2015或者2017直接創建ASP.NET Core的應用程序，也可以使用.NET Core SDK的dotnet new –t web命令在當前文件夾下新建Web項目。本文的演示將基於Visual Studio 2015進行介紹。

添加對Swashbuckle.SwaggerUi和Swashbuckle.SwaggerGen庫的引用

1. 在Web API項目上單擊鼠標右鍵，選擇Manage NuGet Packages：
   
    
2. 在Visual Studio 2015 NuGet標簽頁中，在Browse（瀏覽）tab下，輸入Swashbuckle.SwaggerUi，注意記得勾選“Include prerelease”選項：
   
    
3. 安裝上圖中選中的包到項目中
4. 用上述同樣的方式安裝Swashbuckle.SwaggerGen包到項目中

注意：目前兩個包都還是處於beta的版本，所以需要勾選Include prerelease的選項。

打開XML文檔功能

1. 在Web API項目上點擊鼠標右鍵，選擇Properties（屬性）選項：
   
    
2. 在項目屬性標簽頁中，切換到Build頁面，同時打開XML documentation file選項：
   
    
3. 此時會生成Web API項目代碼的XML文檔。於是，編譯你的項目時會產生一系列的警告信息，因為你暫時還未完成代碼的文檔注釋

修改Startup.cs文件

1. 雙擊打開Startup.cs文件
2. 在ConfigureServices方法中，加入以下代碼，以增加對Swagger的支持：
   

   public void ConfigureServices(IServiceCollection services)
   {
       // Add framework services.
       services.AddMvc();
   
       services.AddSwaggerGen();
       services.ConfigureSwaggerGen(options =>
       {
           options.SingleApiVersion(new Swashbuckle.Swagger.Model.Info
           {
               Version = "v1",
               Title = "My Web Application",
               Description = "RESTful API for My Web Application",
               TermsOfService = "None"
           });
           options.IncludeXmlComments(Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, 
               "WebApplication14.XML")); // 注意：此處替換成所生成的XML documentation的文件名。
           options.DescribeAllEnumsAsStrings();
       });
   }

3. 在Configure方法中，加入以下代碼：
   

   public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
   {
       loggerFactory.AddConsole(Configuration.GetSection("Logging"));
       loggerFactory.AddDebug();
   
       app.UseSwagger();
       app.UseSwaggerUi();
   
       app.UseMvc();
   }

修改Web API項目首頁重定向

1. 在項目上展開Properties節點，雙擊launchSettings.json文件
   
    
2. 根據需要，修改不同profile下的launchUrl的值，比如在本案例中，修改IIS Express節點下的launchUrl，將其改為下圖中的值：
   
    
3. 測試一下，在Visual Studio中，將Web API項目設置成啟動項，然后直接Ctrl+F5啟動項目，你將看到以下畫面：
   
    
4. 在項目中增加一些注釋試試看？打開ValuesController.cs文件，增加一些注釋：
   
    
5. 再次運行站點，發現這些文檔注釋都體現在API頁面中了：
   
    
6. 我們還可以直接在API文檔頁面中進行API的調用測試：
   

 

總結

本文以Walkthrough的方式介紹了如何在ASP.NET Core Web API中增加Swagger API文檔頁面的功能，Swagger是一個非常棒的RESTful API設計、生成、文檔化以及規范化工具，它基於YAML語言，並在官方提供了YAML語言的編輯器。開發人員可以通過各種編輯器，用YAML定義RESTful API的接口契約，同時還可以生成幾十種編程語言的RESTful服務端和客戶端代碼（在上面的截圖中，大家有沒有留意到綠色背景標題欄中的swagger.json文件URL？下載這個文件，然后到官網的編輯器中導入后，即可立刻根據自己的開發語言，下載包含有我們的RESTful API實現的服務端框架和客戶端調用代碼）。這有點像SOAP Web Services時代的WSDL（Web Service描述語言）以及wsdl.exe、svcutil.exe等工具。除了Swagger，RAML也是一種同類產品，有興趣的朋友可以去它們各自的官網了解一下。