Azure 應用服務中的 API 應用、ASP.NET 和 Swagger 入門

時間 2019-11-29

標籤 azure 應用服務 api asp.net asp swagger 入門欄目 ASP 简体版

原文原文鏈接

學習內容：前端

如何經過 Visual Studio 2015 中的內置工具在 Azure 應用服務中建立和部署 API 應用。
如何使用 Swashbuckle NuGet 包動態生成 Swagger API 元數據，以便自動進行 API 發現。
如何使用 Swagger API 元數據自動生成 API 應用的客戶端代碼。

Note

若要將 Visual Studio 鏈接到 Azure 中國區，可按使用 Visual Studio 2015 鏈接中國區 Azure中的說明操做。git

若是使用的是 Visual Studio 2015 Update 2 或更高版本，能夠按照如下圖片中的說明，選中「啓用隔離的 Azure Active Directory 配置」選項。angularjs

若是使用的是 Visual Studio 2017，可按使用 Visual Studio 2017 鏈接中國區 Azure中的說明操做。github

示例應用程序概述

本教程使用簡單的待辦事項列表示例應用程序。該應用程序包含單頁應用程序 (SPA) 前端、ASP.NET Web API 中間層和 ASP.NET Web API 數據層。web

下面是 AngularJS 前端的屏幕截圖。數據庫

Visual Studio 解決方案包含三個項目：json

ToDoListAngular - 前端：用於調用中間層的 AngularJS SPA。api
ToDoListAPI - 中間層：調用數據層，對待辦事項執行 CRUD 操做的 ASP.NET Web API 項目。瀏覽器
ToDoListDataAPI - 數據層：對待辦事項執行 CRUD 操做的 ASP.NET Web API 項目。安全

三層體系結構是可使用 API 應用實現的多種體系結構之一，此處僅用它來進行演示。每一層中的代碼儘量以最簡單的方式來演示 API 應用功能；例如，數據層使用服務器內存而不是數據庫做爲持久性機制。

完成本教程後，將建立兩個在雲中應用服務 API 應用中啓動並運行的 Web API 項目。

本系列教程的下一篇文章會將 SPA 前端部署到雲中。

先決條件

ASP.NET Web API - 本教程中的說明假設讀者基本瞭解如何在 Visual Studio 中使用 ASP.NET Web API 2。
Azure 賬戶 - 能夠打開 Azure 賬戶。
Visual Studio 2015 和用於 .NET 的 Azure SDK - SDK 會自動安裝 Visual Studio 2015（若是還沒有安裝）。
- 在 Visual Studio 中，單擊「幫助」->「關於 Microsoft Visual Studio」，確保安裝了「Azure App Service Tools v2.9.1」或更高版本。
  
  Note
  
  根據計算機上已有 SDK 依賴項數量的不一樣，安裝 SDK 可能耗時較長，從幾分鐘到半小時或更長時間不等。

下載示例應用程序

下載 Azure-Samples/app-service-api-dotnet-to-do-list 存儲庫。

能夠單擊「下載 ZIP」按鈕，或克隆本地計算機上的存儲庫。
在 Visual Studio 2015 或 2013 中打開 ToDoList 解決方案。
1. 須要信任每一個解決方案。
生成解決方案 (CTRL + SHIFT + B) 以還原 NuGet 包。

若是要在部署應用程序以前先查看應用程序的運行狀況，能夠在本地運行此應用程序。確保 ToDoListDataAPI 是啓動項目，而後運行解決方案。應該會在瀏覽器中看到 HTTP 403 錯誤。

使用 Swagger API 元數據和 UI

Azure 應用服務內置 Swagger 2.0 API 元數據支持。每一個 API 應用能夠指定以 Swagger JSON 格式返回 API 元數據的 URL 終結點。從該終結點返回的元數據可用於生成客戶端代碼。

ASP.NET Web API 項目可使用 Swashbuckle NuGet 包動態生成 Swagger 元數據。Swashbuckle NuGet 包已安裝在所下載的 ToDoListDataAPI 和 ToDoListAPI 項目中。

在教程的此部分中查看生成的 Swagger 2.0 元數據，而後嘗試使用基於 Swagger 元數據的測試 UI。

將 ToDoListDataAPI 項目（而不是 ToDoListAPI 項目）設置爲啓動項目。
按 F5 或單擊「調試」>「開始調試」，以調試模式運行項目。

瀏覽器將打開並顯示「HTTP 403 錯誤」頁。

在瀏覽器的地址欄中，於 URL 行尾處添加 swagger/docs/v1，而後按回車鍵。（URL 爲 http://localhost:45914/swagger/docs/v1。）

這是 Swashbuckle 用於返回 API 的 Swagger 2.0 JSON 元數據的默認 URL。

若是使用的是 Internet Explorer，瀏覽器將提示下載 v1.json 文件。

若是使用的是 Chrome、Firefox 或 Edge，瀏覽器將在瀏覽器窗口中顯示 JSON。不一樣的瀏覽器有不一樣的 JSON 處理方式，所以瀏覽器窗口看起來可能與示例不徹底相同。

如下示例顯示了 API 的 Swagger 元數據的第一個部分（包含 Get 方法的定義）。在如下步驟中使用的 Swagger UI 由此元數據驅動，本教程稍後的部分將使用它來自動生成客戶端代碼。

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "ToDoListDataAPI"
  },
  "host": "localhost:45914",
  "schemes": [ "http" ],
  "paths": {
    "/api/ToDoList": {
      "get": {
        "tags": [ "ToDoList" ],
        "operationId": "ToDoList_GetByOwner",
        "consumes": [ ],
        "produces": [ "application/json", "text/json", "application/xml", "text/xml" ],
        "parameters": [
          {
            "name": "owner",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "array",
              "items": { "$ref": "#/definitions/ToDoItem" }
            }
          }
        },
        "deprecated": false
      },

關閉瀏覽器並中止 Visual Studio 調試。
在「解決方案資源管理器」的 ToDoListDataAPI 項目中打開 App_Start\SwaggerConfig.cs 文件，而後向下滾動到第 174 行並將如下代碼取消註釋。
```
/*
    })
.EnableSwaggerUi(c =>
    {
*/
```
SwaggerConfig.cs 文件是在項目中安裝 Swashbuckle 包時建立的。該文件提供配置 Swashbuckle 的多種方式。

已取消註釋的代碼將啓用要在如下步驟中使用的 Swagger UI。做爲一種安全措施，使用 API 應用項目模板建立 Web API 項目時，默認會註釋此代碼。
再次運行該項目。
在瀏覽器的地址欄中，於 URL 行尾處添加 swagger，而後按回車鍵。（URL 爲 http://localhost:45914/swagger。）
當 Swagger UI 頁出現時，請單擊「ToDoList」查看可用方法。
單擊列表中的第一個「Get」按鈕。
在「參數」部分中，輸入星號做爲 owner 參數的值，而後單擊「試用」。

在後續教程中添加身份驗證時，中間層將爲數據層提供實際的用戶 ID。如今，當應用程序在未啓用身份驗證的狀況下運行時，全部任務都以星號做爲其全部者 ID。

Swagger UI 調用 ToDoList Get 方法並顯示響應代碼和 JSON 結果。
單擊「Post」，而後單擊「模型架構」下面的框。

單擊模型架構會預先填充輸入框，能夠在該框中指定 Post 方法的參數值。（若是這不適用於 Internet Explorer，請使用不一樣的瀏覽器或在下一步驟中手動輸入參數值。）
按如下示例中所示，在 todo 參數輸入框中更改 JSON，或者使用本身的描述文本替代：
```
{
  "ID": 2,
  "Description": "buy the dog a toy",
  "Owner": "*"
}
```
單擊「試用」。

ToDoList API 返回表示成功的 HTTP 204 響應碼。
單擊第一個「Get」按鈕，而後在頁面的該部分中單擊「試用」按鈕。

Get 方法響應如今包含新的待辦事項。
可選：還能夠嘗試使用 Put、Delete 和 Get by ID方法。
關閉瀏覽器並中止 Visual Studio 調試。

Swashbuckle 可用於任何 ASP.NET Web API 項目。若是要將 Swagger 元數據生成添加到現有項目，只需安裝 Swashbuckle 包。

Note

Swagger 元數據包含每一個 API 操做的惟一 ID。默認狀況下，Swashbuckle 可能爲 Web API 控制器方法生成重複的 Swagger 操做 ID。若是控制器有重載的 HTTP 方法（例如 Get() 和 Get(id)），就會發生這種狀況。有關如何處理重載的信息，請參閱自定義 Swashbuckle 生成的 API 定義。若是在 Visual Studio 中使用 Azure API 應用模板建立 Web API 項目，SwaggerConfig.cs 文件中會自動添加用於生成惟一操做 ID 的代碼。

在 Azure 中建立 API 應用並向其部署代碼

本部分使用已集成到 Visual Studio 的「發佈 Web」嚮導中的 Azure 工具，在 Azure 中建立新的 API 應用。而後，將 ToDoListDataAPI 項目部署到新的 API 應用，並經過運行 Swagger UI 來調用 API。

在「解決方案資源管理器」中，右鍵單擊 ToDoListDataAPI 項目，而後單擊「發佈」。
在「發佈 Web」嚮導的「配置文件」步驟中，單擊「Azure 應用服務」。
若是還沒有登陸，請登陸到 Azure 賬戶；若是憑據已過時，請刷新憑據。
在「應用服務」對話框中，選擇要使用的 Azure 訂閱，而後單擊「添加」。

此時將顯示「建立應用服務」對話框的「託管」選項卡。

因爲部署的是已安裝 Swashbuckle 的 Web API 項目，所以 Visual Studio 假設要建立 API 應用。「API 應用名稱」標題指出了這一點，另外，從「更改類型」下拉列表已設置爲「API 應用」也能看出這一點。
輸入在 chinacloudsites.cn 域中惟一的 API 應用名稱。能夠接受 Visual Studio 建議的默認名稱。

若是輸入的名稱已被使用，右側會出現紅色感嘆號。

API 應用的 URL 爲 {API app name}.chinacloudsites.cn。
在「資源組」下拉列表中單擊「新建」，而後輸入「ToDoListGroup」或其餘喜愛的名稱。

資源組是 Azure 資源的集合，例如 API 應用、數據庫、VM 等等。在本教程中，最好建立新的資源組，由於這樣能夠經過一個步驟輕鬆刪除針對本教程建立的全部 Azure 資源。

使用此框能夠選擇現有資源組，或經過鍵入與訂閱中任何現有資源組不一樣的名稱，來建立新資源組。
單擊「應用服務計劃」下拉列表旁邊的「新建」按鈕。

屏幕截圖顯示了「API 應用名稱」、「訂閱」和「資源組」的示例值 -- 用戶的值會有所不一樣。

如下步驟爲新資源組建立應用服務計劃。應用服務計劃指定 API 應用運行所在的計算資源。例如，若是你選擇免費層，則 API 應用程序將在共享 VM 上運行；若是你選擇某些付費層，則它在專用 VM 上運行。有關應用服務計劃的信息，請參閱應用服務計劃概述。
在「配置應用服務計劃」對話框中，輸入「ToDoListPlan」或其餘喜愛的名稱。
在「位置」下拉列表中，選擇最靠近的位置。

此設置指定你的應用將在哪一個 Azure 數據中心運行。選擇最靠近的位置，儘可能減小延遲。
在「大小」下拉列表中，單擊「免費」。

對於本教程，免費訂價層便可提供足夠的性能。
在「配置應用服務計劃」對話框中，單擊「肯定」。
在「建立應用服務」對話框中，單擊「建立」。

Visual Studio 將建立 API 應用，以及包含 API 應用所有所需設置的發佈配置文件。而後，將打開「發佈 Web」嚮導來部署項目。

打開的「發佈 Web」嚮導最初顯示「鏈接」選項卡（以下所示）。

在「鏈接」選項卡上，「服務器」和「站點名稱」設置指向 API 應用。「用戶名」和「密碼」是 Azure 建立的部署憑據。部署後，Visual Studio 將在瀏覽器中打開目標 URL（這是目標 URL 的惟一用途）。
單擊「下一步」。

下一個選項卡是「設置」選項卡（以下所示）。能夠在此處更改生成配置選項卡，部署用於遠程調試的調試生成。該選項卡還提供了多個「文件發佈選項」：
- 刪除目標處的其餘文件
- 在發佈期間預編譯
- 從 App_Data 文件夾中排除文件
在本教程中，不須要使用這些選項。有關這些選項的做用的說明，請參閱 How to: Deploy a Web Project Using One-Click Publish in Visual Studio（如何：在 Visual Studio 中使用一鍵式發佈來部署 Web 項目）。
單擊「下一步」。

接下來是「預覽」選項卡（以下所示），用於查看哪些文件即將從項目複製到 API 應用。若是要將項目部署到前面已部署到的 API 應用，則只會複製已更改的文件。若是想要查看要複製的項列表，請單擊「開始預覽」按鈕。
單擊「發佈」。

Visual Studio 隨即將 ToDoListDataAPI 項目部署到新的 API 應用。「輸出」窗口將記錄成功的部署，在打開了 API 應用 URL 的瀏覽器窗口中會出現「已成功建立」頁。
在瀏覽器的地址欄中，將「swagger」添加到 URL，而後按 Enter。（URL 爲 http://{apiappname}.chinacloudsites.cn/swagger。）

瀏覽器將顯示前面出現的相同 Swagger UI，但該 UI 如今在雲中運行。嘗試使用 Get 方法，會發現已返回到默認的 2 個待辦事項。前面所作的更改已保存在本地計算機的內存中。
打開 Azure 門戶。

Azure 門戶是用於管理 Azure 資源（例如 API 應用）的 Web 界面。
單擊「更多服務」>「應用程序服務」。
在「應用程序服務」邊欄選項卡中，找到並單擊新的 API 應用。（在 Azure 門戶中，右側打開的窗口稱爲邊欄選項卡。）

將打開兩個邊欄選項卡。其中一個邊欄選項卡包含 API 應用的概述，另外一個包含能夠查看和更改的一長串設置。
在「設置」邊欄選項卡中，找到「API」部分並單擊「API 定義」。

使用「API 定義」邊欄選項卡能夠指定以 JSON 格式返回 Swagger 2.0 元數據的 URL。當 Visual Studio 建立 API 應用時，會將 API 定義 URL 設置爲前面所示的 Swashbuckle 生成的元數據默認值，即 API 應用的基 URL 加上 /swagger/docs/v1。

選擇要爲其生成客戶端代碼的 API 應用時，Visual Studio 將今後 URL 檢索元數據。