我在開發自己的博客系統（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庫的引用

在Web API項目上單擊鼠標右鍵，選擇Manage NuGet Packages：?
?
?

在Visual Studio 2015 NuGet標簽頁中，在Browse（瀏覽）tab下，輸入Swashbuckle.SwaggerUi，注意記得勾選“Include prerelease”選項：?
?
?

安裝上圖中選中的包到項目中

用上述同樣的方式安裝Swashbuckle.SwaggerGen包到項目中

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

打開XML文檔功能

在Web API項目上點擊鼠標右鍵，選擇Properties（屬性）選項：?
?
?

在項目屬性標簽頁中，切換到Build頁面，同時打開XML documentation file選項：?
?
?

此時會生成Web API項目代碼的XML文檔。于是，編譯你的項目時會產生一系列的警告信息，因為你暫時還未完成代碼的文檔注釋

修改Startup.cs文件

雙擊打開Startup.cs文件

在ConfigureServices方法中，加入以下代碼，以增加對Swagger的支持：?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

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(); ???? }); }

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

1 2 3 4 5 6 7 8 9 10

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

修改Web API項目首頁重定向

在項目上展開Properties節點，雙擊launchSettings.json文件?
?
?

根據需要，修改不同profile下的launchUrl的值，比如在本案例中，修改IIS Express節點下的launchUrl，將其改為下圖中的值：?
?
?

測試一下，在Visual Studio中，將Web API項目設置成啟動項，然后直接Ctrl+F5啟動項目，你將看到以下畫面：?
?
?

在項目中增加一些注釋試試看？打開ValuesController.cs文件，增加一些注釋：?
?
?

再次運行站點，發現這些文檔注釋都體現在API頁面中了：?
?
?

我們還可以直接在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也是一種同類產品，有興趣的朋友可以去它們各自的官網了解

原文地址：http://www.cnblogs.com/daxnet/p/6181366.html

---

.NET社區新聞，深度好文，微信中搜索dotNET跨平臺或掃描二維碼關注

總結

以上是生活随笔為你收集整理的在ASP.NET Core Web API上使用Swagger提供API文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。