我在開發(fā)自己的博客系統(tǒng)（http://daxnet.me）時(shí)，給自己的RESTful服務(wù)增加了基于Swagger的API文檔功能。當(dāng)設(shè)置IISExpress的默認(rèn)啟動(dòng)路由到Swagger的API文檔頁面后，在IISExpress啟動(dòng)Web API站點(diǎn)后，會(huì)自動(dòng)重定向到API文檔頁面，非常方便。這不僅讓我能夠快速省查API設(shè)計(jì)的合理性，同時(shí)從API的使用角度也為我自己提供了便捷。下圖就是我的博客系統(tǒng)RESTful API的Swagger文檔界面：

接下來，讓我們一起看一下如何在ASP.NET Core Web API上實(shí)現(xiàn)這一基于Swagger的API文檔頁面。

實(shí)現(xiàn)步驟

創(chuàng)建ASP.NET Web API應(yīng)用程序

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

添加對(duì)Swashbuckle.SwaggerUi和Swashbuckle.SwaggerGen庫的引用

在Web API項(xiàng)目上單擊鼠標(biāo)右鍵，選擇Manage NuGet Packages：?
?
?

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

安裝上圖中選中的包到項(xiàng)目中

用上述同樣的方式安裝Swashbuckle.SwaggerGen包到項(xiàng)目中

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

打開XML文檔功能

在Web API項(xiàng)目上點(diǎn)擊鼠標(biāo)右鍵，選擇Properties（屬性）選項(xiàng)：?
?
?

在項(xiàng)目屬性標(biāo)簽頁中，切換到Build頁面，同時(shí)打開XML documentation file選項(xiàng)：?
?
?

此時(shí)會(huì)生成Web API項(xiàng)目代碼的XML文檔。于是，編譯你的項(xiàng)目時(shí)會(huì)產(chǎn)生一系列的警告信息，因?yàn)槟銜簳r(shí)還未完成代碼的文檔注釋

修改Startup.cs文件

雙擊打開Startup.cs文件

在ConfigureServices方法中，加入以下代碼，以增加對(duì)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項(xiàng)目首頁重定向

在項(xiàng)目上展開Properties節(jié)點(diǎn)，雙擊launchSettings.json文件?
?
?

根據(jù)需要，修改不同profile下的launchUrl的值，比如在本案例中，修改IIS Express節(jié)點(diǎn)下的launchUrl，將其改為下圖中的值：?
?
?

測(cè)試一下，在Visual Studio中，將Web API項(xiàng)目設(shè)置成啟動(dòng)項(xiàng)，然后直接Ctrl+F5啟動(dòng)項(xiàng)目，你將看到以下畫面：?
?
?

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

再次運(yùn)行站點(diǎn)，發(fā)現(xiàn)這些文檔注釋都體現(xiàn)在API頁面中了：?
?
?

我們還可以直接在API文檔頁面中進(jìn)行API的調(diào)用測(cè)試：?

總結(jié)

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

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

---

.NET社區(qū)新聞，深度好文，微信中搜索dotNET跨平臺(tái)或掃描二維碼關(guān)注

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。