在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也是一種同類產品，有興趣的朋友能夠去它們各自的官網瞭解一下。