Visual Studio 2017 and Swagger: Building and Documenting Web APIs

Swagger是一種與技術無關的標准，允許發現REST API，為任何軟件提供了一種識別REST API功能的方法。

這比看起來更重要：這是一個改變游戲技術的方式，就像Web服務描述語言一樣WSDL（Web Service Description Language）一樣。

WSDL一直是使Visual Studio等工具和IDE 可以理解Web服務並創建代理類的基礎技術。此功能將Web服務的消耗轉換為高級任務，封裝所有協議詳細信息。

這是Swagger的重要性：它可以為REST API做出WSDL已經為Web服務所做的工作，允許創建代理和使用Web API更容易。

VS 2017包括使用Swagger協議支持REST API代理創建。它還處於早期階段，缺乏一些特點，但這是向廣泛采用Swagger邁出的重要一步。

我們將創建一個例子，說明我們如何使用Swagger與VS 2017來分析優勢和缺少的功能。

以及VS 2017，我們還將需要安裝在開發機器中的IIS（Internet Information Server）作為示例。

發展環境

您可以將IIS作為Windows功能或服務器角色啟用，具體取決於您是否使用客戶端操作系統或服務器角色。

開始申請

在我們可以使用Swagger之前，我們需要一個具有Web API項目的演示解決方案。我們來構建這個開始的解決方案，然后再繼續實施Swagger。

1. 創建ASP.NET Web API項目
   1. 在Visual Studio中，選擇“文件” - > “新建項目”菜單
   2. 在“新建項目”對話框的左側樹視圖中，選擇“已安裝” - > “模板” - > “Visual C＃” - > “Web”樹項目。
   3. 在“新建項目”對話框的右側，選擇“ASP.NET Web應用程序（.NET Framework）”

在“名稱”文本框中，鍵入“webDemo”

1. 1. 在“解決方案名稱”文本框中，鍵入“slDemo”，然后單擊“確定”按鈕

在“新ASP.NET Web應用程序”窗口中，在“ASP.NET 4.5.2模板”下，選擇“Web API”，然后單擊“確定”按鈕

1. 配置Web API項目以使用本地IIS
   1. 在“解決方案資源管理器”窗口中，右鍵單擊“webDemo”項目，然后單擊“屬性”菜單項。
   2. 在“webDemo”屬性窗口的右側，單擊“Web”頁面

在“服務器”下的組合框中，選擇“本地IIS”

1. 1. 單擊“創建虛擬目錄”按鈕
   2. 關閉'webDemo'屬性頁面

該項目已經開發了一個Web API控件示例，但是我們需要進行一些更改。我們來看一下現有控制器的細節，並做出這些改變。

1. 分析和更改現有的API控制器
   1. 在“解決方案資源管理器”窗口的“webDemo”項目中，打開“控制器”文件夾並檢查現有的控制器。

      

   2. 雙擊“ValuesController.cs”文件並檢查現有操作。這是項目中唯一的Web API控制器。

更改下面的代碼的“ValuesController”類。我們正在完成PUT操作並將該列表存儲在Application memory區域內。

 

public class ValuesController : ApiController       {           private string[] lista           {               get               {                   if (System.Web.HttpContext.Current.Application[<em>"lista"</em>]==null)                   {                       System.Web.HttpContext.Current.Application[<em>"lista"</em>] =                           new string[] { <em>"value1"</em>, <em>"value2"</em> };                   }                   return                       (string[])System.Web.HttpContext.Current.Application[<em>"lista"</em>];               }           }           public IEnumerable<string> Get()           {               return lista;           }           public string Get(int id)           {               return lista[id];           }           public void Post([FromBody]string value)           {           }           public void Put(int id, [FromBody]string value)           {               lista[id] = value;           }           public void Delete(int id)           {           }       }

1. 執行應用程序並分析結果
1. 單擊工具欄中的“開始”按鈕執行應用程序

在剛剛打開的網頁上，點擊頂部菜單中的“API”鏈接。您將注意到API操作，基本上是一個具有兩個GET的 CRUD ，一個POST，PUT和DELETE

在瀏覽器導航欄中，鍵入新的URL：http：// localhost / webDemo / API / Values。因此，將下載一個JSON文件，因此該Web API正常工作。

在我們的項目中包括Swagger

Swagger是一項技術無關的協議。對於每種技術，我們需要一些實現協議的工具。SwashBuckle是.NET工具的名稱。4.5之前的.NET版本和4.5之后的.NET的另一個版本。

讓我們逐步練習使用SwashBuckle來實現Swagger ：

1. 在Web API項目中 包含SwashBuckle nugget包
   1. 在“ 解決方案資源管理器”窗口中，右鍵單擊“webDemo”項目，然后單擊“管理nuget數據包”菜單項。
   2. 在“Nuget包管理器”窗口中，選擇“瀏覽”
   3. 在“Nuget軟件包管理器”窗口中的文本框中，鍵入“SwashBuckle”。

在“Nuget軟件包管理器”窗口的左側，選擇“SwashBuckle.Net45”軟件包

1. 1. 在“Nuget軟件包管理器”窗口的右側，單擊“安裝”按鈕。
   2. 在“查看更改”窗口中，單擊“確定”按鈕。
   3. 在“許可驗收”窗口中，單擊“我接受”按鈕。
   4. 關閉“Nuget軟件包管理器”窗口
2. 配置XML文檔。SwashBuckle將使用XML文檔來描述WEB API操作。
   1. 在“解決方案資源管理器”窗口中，右鍵單擊“webDemo”項目，然后單擊“屬性”菜單項。
   2. 在“webDemo”窗口中，單擊“構建”頁面

在'webDemo'窗口中的“輸出”下方，單擊“Xml文檔文件”復選框。在右邊的文本框中，您將看到路徑“bin \ webDemo.xml”。

1. 1. 在“解決方案資源管理器”窗口的“webDemo”項目中，打開“控制器”文件夾，然后雙擊“ValuesController.cs”文件。
   2. 我們為每個動作和控制器創建一個XML文檔。通過每個動作，並通過控制器聲明，鍵入'///'並描述動作和控制器。
      
              /// <summary>

                /// Retrieves the list of values

                /// </summary>

                /// <returns></returns>

                public IEnumerable<string> Get()

                {

                    return lista;

                }

                /// <summary>

                /// Retrieves one value from the list of values

                /// </summary>

                /// <param name=<em>"id"</em>>The id of the item to be retrieved</param>

                /// <returns></returns>

                public string Get(int id)

                {

                    return lista[id];

                }

                /// <summary>

                /// Insert a new value in the list

                /// </summary>

                /// <param name=<em>"value"</em>>New value to be inserted</param>

                public void Post([FromBody]string value)

                {

                }

                /// <summary>

                /// Change a single value in the list

                /// </summary>

                /// <param name=<em>"id"</em>>The id of the value to be changed</param>

                /// <param name=<em>"value"</em>>The new value</param>

                public void Put(int id, [FromBody]string value)

                {

                    lista[id] = value;

                }

                /// <summary>

                /// Delete an item from the list

                /// </summary>

                /// <param name=<em>"id"</em>>id of the item to be deleted</param>

                public void Delete(int id)

                {

                }
2. 配置SwashBuckle。現在，我們需要做的唯一配置就是XML文檔的路徑。
3. 在“解決方案資源管理器”窗口的“webDemo”項目中，打開“App_Start”文件夾，然后雙擊“SwaggerConfig.cs”文件。該文件由“SwashBuckle.Net45” nuget軟件包包含在該項目中。

   

   “SwaggerConfig”類 的“注冊”方法被配置為作為“PreApplicationStartMethod”執行。

   1. 在“SwaggerConfig”類中包含以下方法：
      
              protected static string GetXmlCommentsPath()

                {

                    return System.String.Format(@<em>"{0}\bin\webDemo.XML"</em>,

                        System.AppDomain.CurrentDomain.BaseDirectory);

                }
   2. 在“注冊”方法中取消注釋以下代碼塊：
      
                              c.IncludeXmlComments(GetXmlCommentsPath());
4. 執行並測試應用程序
   1. 執行應用程序，單擊工具欄中的“開始”按鈕。
   2. 在瀏覽器地址欄中輸入以下URL：http：// localhost / webDemo / Swagger / ui / index

在Swagger文檔頁面上，單擊“值”，控制器的名稱。

1. 1. 單擊每個操作以查看文檔。您可能會注意到Swagger正在使用每個操作的XML文檔描述。
   2. 在瀏覽器地址欄中輸入以下URL：http：// localhost / webDemo / Swagger / docs / v1。這一次我們正在尋找描述Web API 的JSON文檔，這是SwashBuckle的核心結果
   3. 在出現的問題中，點擊“保存”按鈕（我正在使用Chrome，這可能與其他瀏覽器有所不同）
   4. 在出現的消息中，單擊“打開文件夾”按鈕。（我正在使用Chrome，這可能與其他瀏覽器有所不同）

用記事本 打開v1.json文件。該文件的格式不會很好，但內容卻是對Web API的描述，如下圖所示。如果您願意，可以在Visual Studio中打開該文件，以查看文件格式正確的版本。

1. 1. 停止Visual Studio中的執行

創建客戶端項目

現在是時候創建一個客戶端來消費我們的Web API，並說明這個消費將如何容易多了。

1. 向該解決方案添加一個新的Windows桌面項目
   1. 在Visual Studio中，單擊菜單中的 “文件” - > “添加” - > “新建項目”
   2. 在“新建項目”對話框的左側樹視圖中，選擇“安裝” - > “模板” - > “Visual C＃” - > “Windows經典桌面”樹項目。
   3. 在“新建項目”對話框的右側，選擇“Windows Forms App（.NET Framework）”
   4. 在“名稱”文本框中，鍵入“winClient”，然后單擊“確定”按鈕
2. 添加對Web API的引用並創建代理

在“解決方案資源管理器”窗口中，右鍵單擊“winClient”項目，單擊“添加” - > “REST API客戶端”菜單項。

1. 1. In the ‘Add REST API Client’ window, ‘Swagger Url’ textbox, type http://localhost/webDemo/Swagger/docs/v1 .

In the ‘Client Namespace’ textbox, type ‘SvcRest’ and click the ‘Ok’ button.

It seems that nothing happened. Inside ‘Web Publish Activity’ window you will be able to see what happened and an error message: ‘Found operation object with duplicate OperationId ‘Values_Get’. OperationId must be unique among all operations described in the API’.

The client tool doesn’t support a REST API with operation overload, and our demo API has two GET methods. We need to resolve this problem before we proceed.

Support for operation overload

這種缺乏對操作超載的支持是一個很大的缺陷，因為即使是您可能注意到的演示Web API應用程序也使用操作重載，它有兩個GET操作，帶有和不帶參數。

有兩種可能的解決方案：

• 更改操作名稱以避免過載
• 實現一個可以攔截JSON文件創建的操作過濾器，避免JSON文件中的重載。

讓我們逐步實現一個操作過濾器：

1. 為解決方案添加一個新的類庫
   1. 在“ 解決方案資源管理器”窗口中，右鍵單擊解決方案，單擊“添加” - > “新建項目”上下文菜單項
   2. 在“新建項目”對話框的左側樹視圖中，選擇“安裝” - > “模板” - > “Visual C＃” - > “Windows經典桌面”樹項目。
   3. 在“新建項目”對話框的右側，選擇“類庫（.NET Framework）”

在“名稱”文本框中，鍵入“libTools”，然后單擊“確定”按鈕

1. 1. 在“解決方案資源管理器”窗口中，右鍵單擊“Class1.cs”文件，在“libTools”項目下，單擊“刪除”菜單項。
2. 在新的Class Library項目中 安裝“SwashBuckle.Core.Net45”軟件包。我只安裝SwashBuckle的核心，而不是所有的庫。
   1. 在“解決方案資源管理器”窗口中，右鍵單擊“libTools”項目，然后單擊“管理nuget數據包”菜單項。
   2. 在“Nuget包管理器”窗口中，選擇“瀏覽”
   3. 在“Nuget軟件包管理器”窗口中的文本框中，鍵入“SwashBuckle”。
   4. 在“Nuget包管理器”窗口的左側，選擇“SwashBuckle.Core.Net45”包
   5. 在“Nuget軟件包管理器”窗口的右側，單擊“安裝”按鈕。
   6. 在“查看更改”窗口中，單擊“確定”按鈕。
   7. 在“許可驗收”窗口中，單擊“我接受”按鈕。
3. 實現操作過濾器
   1. 在“解決方案資源管理器”窗口中，右鍵單擊“libTools”項目，單擊“添加” - > “類...”上下文菜單項

在“添加新項目”窗口中，在“名稱”文本框中鍵入“MultipleOperationsWithSameVerbFilter.cs”。

1. 1. 復制下面的代碼並粘貼到新文件中，替換空類：
      
          using Swashbuckle.Swagger;

            using System.Web.Http.Description;

            public class MultipleOperationsWithSameVerbFilter : IOperationFilter

            {

                public void Apply(

                    Operation operation,

                    SchemaRegistry schemaRegistry,

                    ApiDescription apiDescription)

                {

                    if (operation.parameters != null)

                    {

                        operation.operationId += "By";

                        foreach (var parm in operation.parameters)

                        {

                            operation.operationId += string.Format("{0}",

                                parm.name);

                        }

                    }

                }
2. 在“webDemo”工程，引用添加到“libTools”項目
   1. 在“解決方案資源管理器”窗口中，右鍵單擊“webDemo”項目，單擊“添加” - > “參考”上下文菜單項
   2. 在“參考管理器”窗口的左側，選擇“項目” - > “解決方案”項

在“參考管理器”窗口的右側，選中'libTools'以外的框，然后單擊“確定”按鈕

1. 更改Swagger配置以使用新的操作過濾器
   1. 在“解決方案資源管理器”窗口的“webDemo”項目中，打開“App_Start”文件夾，然后雙擊“SwaggerConfig.cs”文件。
   2. 在“SwaggerConfig.cs”文件的頂部，添加以下行：
      
      using libTools;
   3. 在“注冊”方法中，在以下塊中：
      
                  GlobalConfiguration.Configuration

                        .EnableSwagger(c =>

                            {

      添加以下代碼行：

                              c.OperationFilter<MultipleOperationsWithSameVerbFilter>();

在“解決方案資源管理器”窗口中，右鍵單擊解決方案，然后單擊“重建解決方案”菜單項

1. 重復客戶端代理創建的步驟2，這一次它將工作。

在客戶端應用程序中使用代理

現在Web API代理是建立在客戶端項目中的，現在是使用它來訪問Web API的時候了。但是，代理需要一個額外的類來控制身份驗證。這個功能的另一個缺點是它對匿名認證的處理不好，但是我們可以通過快速解決來克服這個問題。

1. 在'libTools'項目中 安裝'Microsoft.Rest.ClientRuntime'包。這個包是我們修復需要的。
   1. 在“解決方案資源管理器”窗口中，右鍵單擊“libTools”項目，然后單擊“管理nuget數據包”菜單項。
   2. 在“Nuget包管理器”窗口中，選擇“瀏覽”
   3. 在“Nuget軟件包管理器”窗口的文本框中，鍵入“Microsoft.Rest.ClientRuntime”。
   4. 在“Nuget包管理器”窗口的左側，選擇“Microsoft.Rest.ClientRuntime”包
   5. 在“Nuget軟件包管理器”窗口的右側，單擊“安裝”按鈕。
   6. 在“查看更改”窗口中，單擊“確定”按鈕。
   7. 在“許可驗收”窗口中，單擊“我接受”按鈕。
2. 實現AnonymousCredential類。這將會導致匿名認證問題。
   1. 在“解決方案資源管理器”窗口中，右鍵單擊“libTools”項目，然后單擊“添加” - > “類”上下文菜單項。
   2. 在“添加新項目”對話框中，在“名稱”文本框中鍵入“AnonymousCredential.cs”，然后單擊“確定”按鈕
   3. 在新文件的頂部，添加以下語句：
      
      using Microsoft.Rest;
   4. 為此類使用以下代碼。是的，沒有什么需要，但繼承。
      
      public class AnonymousCredential : ServiceClientCredentials

        {

        }
3. 3）構建客戶端Windows窗體來訪問API
   1. 在“解決方案資源管理器”窗口中的“winClient”項目下，雙擊“Form1.cs”文件。
   2. 從“工具箱”窗口中，在表單中添加三個按鈕。

根據以下內容更改按鈕屬性：

名稱：cmdAllValues 

文本：所有值

名稱：cmdValue 

文本：單值

名稱：cmdUpdate 

文本：更新

1. 1. 在Windows項目中，添加對'libTools'項目的引用
      1. 在“解決方案資源管理器”窗口中，右鍵單擊“winClient”項目，單擊“添加” - > “參考”上下文菜單項
      2. 在“參考管理器”窗口的左側，選擇“項目” - > “解決方案”項
      3. 在“參考管理器”窗口的右側，選中'libTools'以外的框，然后單擊“確定”按鈕
   2. 添加“所有值”按鈕的代碼
      1. 選擇“Form1.cs（design）”頁面
      2. 雙擊“所有值”按鈕，這將為按鈕創建一個點擊事件。
      3. 在“Form1.cs”文件的頂部（由上一個任務已經打開），添加以下語句：
         
         using libTools;

           using svcRest;
      4. 更改以下代碼的“cmdAllValues_Click”：
         
                 private async void cmdAllValues_Click(object sender, EventArgs e)

                   {

                       SvcRestClient client =

                           new SvcRestClient(new Uri("http://localhost/webDemo"),

                               new AnonymousCredential());

                       var result = client.Values.Get();

                   

                       foreach(var x in result)

                       {

                           MessageBox.Show(x);

                       }

                   }

         請注意以下細節：

         • 代理中有兩種，同步和異步方法。代碼說明了同步調用。
         • 大多數方法是擴展方法：因為這樣，我們需要使用“使用svcRest”語句。
         • 您不需要處理調用API的協議詳細信息。這是代理的優勢。自.NET創建以來，我們對webservices有這個優勢; 現在我們可以用這種方式使用web API。
   3. 添加“單值”按鈕的代碼
      1. 選擇“Form1.cs（design）”頁面
      2. 雙擊“單一值”按鈕，這將為按鈕創建一個點擊事件。
      3. 更改以下代碼的“cmdValue_Click”：
         
                 private async void cmdValue_Click(object sender, EventArgs e)

                   {

                       SvcRestClient client =

                           new SvcRestClient(new Uri("http://localhost/webDemo"),

                             new AnonymousCredential());

                       var result = client.Values.GetByid(1);

                       MessageBox.Show(result);

                   }
   4. 添加“更新”按鈕的代碼
      1. 選擇“Form1.cs（design）”頁面
      2. 雙擊“更新”按鈕，這將為按鈕創建一個點擊事件。
      3. 更改以下代碼的“cmdUpdate_Click”：
         
                 private async void cmdUpdate_Click(object sender, EventArgs e)

                   {

                       SvcRestClient client =

                           new SvcRestClient(new Uri("http://localhost/webDemo"),

                             new AnonymousCredential());

                       client.Values.PutByidvalue(1, "New Value");

                           

                       MessageBox.Show("Change Completed!");

                   }
   5. 執行並測試應用程序
      1. 在“解決方案資源管理器”窗口中，右鍵單擊“winClient”項目，然后單擊“設為啟動項目”
      2. 單擊工具箱中的“開始”按鈕運行應用程序
      3. 點擊“所有值”按鈕，“單一值”按鈕，“更新”按鈕和“單一值”按鈕，並在需要時單擊“確定”按鈕，以檢查結果。API調用將運行良好。