Azure 应用服务中的 API 应用、ASP.NET 和 Swagger 入门

学习内容：

如何通过 Visual Studio 2015 中的内置工具在 Azure 应用服务中创建和部署 API 应用。
如何使用 Swashbuckle NuGet 包动态生成 Swagger API 元数据，以便自动进行 API 发现。
如何使用 Swagger API 元数据自动生成 API 应用的客户端代码。

Note

若要将 Visual Studio 连接到 Azure 中国区，可按使用 Visual Studio 2015 连接中国区 Azure中的说明操作。

如果使用的是 Visual Studio 2015 Update 2 或更高版本，可以按照以下图片中的说明，选中“启用隔离的 Azure Active Directory 配置”选项。

enable-isolated-azure-active-directory-configuration

如果使用的是 Visual Studio 2017，可按使用 Visual Studio 2017 连接中国区 Azure中的说明操作。

示例应用程序概述

本教程使用简单的待办事项列表示例应用程序。该应用程序包含单页应用程序 (SPA) 前端、ASP.NET Web API 中间层和 ASP.NET Web API 数据层。

API 应用示例应用程序示意图

下面是 AngularJS 前端的屏幕截图。

API 应用示例应用程序待办事项列表

Visual Studio 解决方案包含三个项目：

ToDoListAngular - 前端：用于调用中间层的 AngularJS SPA。
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 文件。

在 IE 中下载 JSON 元数据

如果使用的是 Chrome、Firefox 或 Edge，浏览器将在浏览器窗口中显示 JSON。不同的浏览器有不同的 JSON 处理方式，因此浏览器窗口看起来可能与示例不完全相同。

Chrome 中的 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 检索元数据。

更多学习资料