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 配置”选项。

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

示例应用程序概述

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

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

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 可能耗时较长，从几分钟到半小时或更长时间不等。

下载示例应用程序

  1. 下载 Azure-Samples/app-service-api-dotnet-to-do-list 存储库。

    可以单击“下载 ZIP”按钮，或克隆本地计算机上的存储库。

  2. 在 Visual Studio 2015 或 2013 中打开 ToDoList 解决方案。
    1. 需要信任每个解决方案。
  3. 生成解决方案 (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。

  1. 将 ToDoListDataAPI 项目（而不是 ToDoListAPI 项目）设置为启动项目。

  2. 按 F5 或单击“调试”>“开始调试”，以调试模式运行项目。

    浏览器将打开并显示“HTTP 403 错误”页。

  3. 在浏览器的地址栏中，于 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
      },
  4. 关闭浏览器并停止 Visual Studio 调试。
  5. 在“解决方案资源管理器”的 ToDoListDataAPI 项目中打开 App_Start\SwaggerConfig.cs 文件，然后向下滚动到第 174 行并将以下代码取消注释。

    复制

    /*
    })
.EnableSwaggerUi(c =>
    {
*/

    SwaggerConfig.cs 文件是在项目中安装 Swashbuckle 包时创建的。该文件提供配置 Swashbuckle 的多种方式。

    已取消注释的代码将启用要在以下步骤中使用的 Swagger UI。作为一种安全措施，使用 API 应用项目模板创建 Web API 项目时，默认会注释此代码。

  6. 再次运行该项目。
  7. 在浏览器的地址栏中，于 URL 行尾处添加 swagger，然后按回车键。（URL 为 http://localhost:45914/swagger。）
  8. 当 Swagger UI 页出现时，请单击“ToDoList”查看可用方法。

  9. 单击列表中的第一个“Get”按钮。
  10. 在“参数”部分中，输入星号作为 owner 参数的值，然后单击“试用”。

    在后续教程中添加身份验证时，中间层将为数据层提供实际的用户 ID。现在，当应用程序在未启用身份验证的情况下运行时，所有任务都以星号作为其所有者 ID。

    Swagger UI 调用 ToDoList Get 方法并显示响应代码和 JSON 结果。

  11. 单击“Post”，然后单击“模型架构”下面的框。

    单击模型架构会预先填充输入框，可以在该框中指定 Post 方法的参数值。（如果这不适用于 Internet Explorer，请使用不同的浏览器或在下一步骤中手动输入参数值。）

  12. 按以下示例中所示，在 todo 参数输入框中更改 JSON，或者使用自己的描述文本替代：

    复制

    {
  "ID": 2,
  "Description": "buy the dog a toy",
  "Owner": "*"
}
  13. 单击“试用”。

    ToDoList API 返回表示成功的 HTTP 204 响应码。

  14. 单击第一个“Get”按钮，然后在页面的该部分中单击“试用”按钮。

    Get 方法响应现在包含新的待办事项。

  15. 可选：还可以尝试使用 Put、Delete 和 Get by ID方法。
  16. 关闭浏览器并停止 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。

  1. 在“解决方案资源管理器”中，右键单击 ToDoListDataAPI 项目，然后单击“发布”。

  2. 在“发布 Web”向导的“配置文件”步骤中，单击“Azure 应用服务”。

  3. 如果尚未登录，请登录到 Azure 帐户；如果凭据已过期，请刷新凭据。
  4. 在“应用服务”对话框中，选择要使用的 Azure 订阅，然后单击“添加”。

    此时将显示“创建应用服务”对话框的“托管”选项卡。

    由于部署的是已安装 Swashbuckle 的 Web API 项目，因此 Visual Studio 假设要创建 API 应用。“API 应用名称”标题指出了这一点，另外，从“更改类型”下拉列表已设置为“API 应用”也能看出这一点。

  5. 输入在 chinacloudsites.cn 域中唯一的 API 应用名称。可以接受 Visual Studio 建议的默认名称。

    如果输入的名称已被使用，右侧会出现红色感叹号。

    API 应用的 URL 为 {API app name}.chinacloudsites.cn。

  6. 在“资源组”下拉列表中单击“新建”，然后输入“ToDoListGroup”或其他喜好的名称。

    资源组是 Azure 资源的集合，例如 API 应用、数据库、VM 等等。在本教程中，最好创建新的资源组，因为这样可以通过一个步骤轻松删除针对本教程创建的所有 Azure 资源。

    使用此框可以选择现有资源组，或通过键入与订阅中任何现有资源组不同的名称，来创建新资源组。

  7. 单击“应用服务计划”下拉列表旁边的“新建”按钮。

    屏幕截图显示了“API 应用名称”、“订阅”和“资源组”的示例值 -- 用户的值会有所不同。

    以下步骤为新资源组创建应用服务计划。应用服务计划指定 API 应用运行所在的计算资源。例如，如果你选择免费层，则 API 应用程序将在共享 VM 上运行；如果你选择某些付费层，则它在专用 VM 上运行。有关应用服务计划的信息，请参阅应用服务计划概述。

  8. 在“配置应用服务计划”对话框中，输入“ToDoListPlan”或其他喜好的名称。
  9. 在“位置”下拉列表中，选择最靠近的位置。

    此设置指定你的应用将在哪个 Azure 数据中心运行。选择最靠近的位置，尽量减少延迟。

  10. 在“大小”下拉列表中，单击“免费”。

    对于本教程，免费定价层即可提供足够的性能。

  11. 在“配置应用服务计划”对话框中，单击“确定”。

  12. 在“创建应用服务”对话框中，单击“创建”。

    Visual Studio 将创建 API 应用，以及包含 API 应用全部所需设置的发布配置文件。然后，将打开“发布 Web”向导来部署项目。

    打开的“发布 Web”向导最初显示“连接”选项卡（如下所示）。

    在“连接”选项卡上，“服务器”和“站点名称”设置指向 API 应用。“用户名”和“密码”是 Azure 创建的部署凭据。部署后，Visual Studio 将在浏览器中打开目标 URL（这是目标 URL 的唯一用途）。

  13. 单击“下一步”。

    下一个选项卡是“设置”选项卡（如下所示）。可以在此处更改生成配置选项卡，部署用于远程调试的调试生成。该选项卡还提供了多个“文件发布选项”：

    • 删除目标处的其他文件
    • 在发布期间预编译
    • 从 App_Data 文件夹中排除文件

    在本教程中，不需要使用这些选项。有关这些选项的作用的说明，请参阅 How to: Deploy a Web Project Using One-Click Publish in Visual Studio（如何：在 Visual Studio 中使用一键式发布来部署 Web 项目）。

  14. 单击“下一步”。

    接下来是“预览”选项卡（如下所示），用于查看哪些文件即将从项目复制到 API 应用。如果要将项目部署到前面已部署到的 API 应用，则只会复制已更改的文件。如果想要查看要复制的项列表，请单击“开始预览”按钮。

  15. 单击“发布”。

    Visual Studio 随即将 ToDoListDataAPI 项目部署到新的 API 应用。“输出”窗口将记录成功的部署，在打开了 API 应用 URL 的浏览器窗口中会出现“已成功创建”页。

  16. 在浏览器的地址栏中，将“swagger”添加到 URL，然后按 Enter。（URL 为 http://{apiappname}.chinacloudsites.cn/swagger。）

    浏览器将显示前面出现的相同 Swagger UI，但该 UI 现在在云中运行。尝试使用 Get 方法，会发现已返回到默认的 2 个待办事项。前面所做的更改已保存在本地计算机的内存中。

  17. 打开 Azure 门户。

    Azure 门户是用于管理 Azure 资源（例如 API 应用）的 Web 界面。

  18. 单击“更多服务”>“应用程序服务”。

  19. 在“应用程序服务”边栏选项卡中，找到并单击新的 API 应用。（在 Azure 门户中，右侧打开的窗口称为边栏选项卡。）

    将打开两个边栏选项卡。其中一个边栏选项卡包含 API 应用的概述，另一个包含可以查看和更改的一长串设置。

  20. 在“设置”边栏选项卡中，找到“API”部分并单击“API 定义”。

    使用“API 定义”边栏选项卡可以指定以 JSON 格式返回 Swagger 2.0 元数据的 URL。当 Visual Studio 创建 API 应用时，会将 API 定义 URL 设置为前面所示的 Swashbuckle 生成的元数据默认值，即 API 应用的基 URL 加上 /swagger/docs/v1。

    选择要为其生成客户端代码的 API 应用时，Visual Studio 将从此 URL 检索元数据。

更多学习资料

时间： 2024-10-08 00:15:28

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

在 Azure WebApps 中运行64位 Asp.net Core 应用

作为微软下一代的开源的跨平台的开发框架, Asp.net core 正在吸引越来越多的开发者基于其构建现代 web 应用. 目前, Azure App Service 也实现了对 asp.net core 的支持. 用户所开发的 ASP.NET Core Web 应用, 以与通常 Asp.net Web 应用同样的方式部署到云端后,便可以被顺利执行. 但是,目前 Azure App Service 尚只支持32位的 Asp.net Core 运行时,即用户的 Asp.net Core 应用在云端

NHibernate中的API

本篇文章介绍的是NHibernate的各种API及其作用. 下图描述了NHibernate的API在分层架构中的作用,下面将进行详细说明. NHibernate的接口大致分为四类:1.  被应用程序调用进行基本数据操作(增.删.改.查)的接口.这些接口是应用程序的业务逻辑层和控制层与NHibernate的主要交互点.ISession, ITransaction, IQuery和ICriteria属于此类.2. 被应用程序用来配置NHibernate的接口.Configuration就属此类.3.

如何通过Azure Service Management REST API管理Azure服务

通过本文你将了解: 什么是Azure Service Management REST API 如何获取微软Azure 订阅号 如何获取Azure管理证书 如何调用Azure Service Management REST API 什么是Azure Service Management REST API Azure Service Management REST API(之后简称为Azure REST API)是微软开放的一组REST API,它使得Azure用户不仅可以从Azure门户网站上对运

如何在Google Map中处理大量标记(ASP.NET)(转)

如何在Google Map中处理大量标记(ASP.NET)(原创-翻译) Posted on 2010-07-29 22:04 Happy Coding 阅读(8827) 评论(8) 编辑 收藏 在你有一个合理的标记数量的时候,使Google Map标记是很平常的.但是一旦你有几百个.甚至更多地标的时候,性能迅速的开始降低.在本文章中,我会告诉你一些提高性能的方法.同时我会放一个测试页面去比较它们的效率. 如果你是第一次使用Google Map的标记,我建议你先去了解一下在Google Map上

Asp.Net Web API VS Asp.Net MVC

http://www.dotnet-tricks.com/Tutorial/webapi/Y95G050413-Difference-between-ASP.NET-MVC-and-ASP.NET-Web-API.html Asp.Net MVC is used to create web applications that returns both views and data but Asp.Net Web API is used to create full blown HTTP serv

Designing Evolvable Web API with ASP.NET 随便读，随便记 “The Internet,the World Wide Web,and HTTP”——HTTP

HTTP 我们将只聚焦在于与创建 Web APIs有关的部分. HTTP 是信息系统中的一个应用层协议,是Web的支柱. 其原先由 Berners-Lee, Roy Fielding 和 Henrik Frystyk Nielsen 三位计算机科学家们创作的.HTTP 为 客户端与服务器端之间跨网络相互传输信息定义了一个接口.它隐藏了双方的实现细 节. HTTP 设计用来戏剧性地改变系统,而容许一定程度上的延迟和数据的过时. 这种设计允许 计算机中间媒体,如代理服务器来协调通信,提供诸多好处,

谈谈微服务中的 API 网关（API Gateway）

转载至:http://www.cnblogs.com/savorboard/p/api-gateway.html 背景 我们知道在微服务架构风格中,一个大应用被拆分成为了多个小的服务系统提供出来,这些小的系统他们可以自成体系,也就是说这些小系统可以拥有自己的数据库,框架甚至语言等,这些小系统通常以提供 Rest Api 风格的接口来被 H5, Android, IOS 以及第三方应用程序调用. 但是在UI上进行展示的时候,我们通常需要在一个界面上展示很多数据,这些数据可能来自于不同的微服务中,举

.Net Core中的Api版本控制

原文链接:API Versioning in .Net Core 作者:Neel Bhatt 简介 Api的版本控制是Api开发中经常遇到的问题, 在大部分中大型项目都需要使用到Api的版本控制 在本篇博客中,我们将说明一下如何在.Net Core Api项目中使用Api版本控制. 本篇博客中测试项目的开发环境: Visual Studio 2017 .Net Core 2.1 SDK .Net Core Api中使用Api版本控制 创建一个Api项目 首先我们创建一个.NET Core Api

如何将Azure DevOps中的代码发布到Azure App Service中

标题:如何将Azure DevOps中的代码发布到Azure App Service中 作者:Lamond Lu 背景 最近做了几个项目一直在用Azure DevOps和Azure App Service, 每次都要从零开始搭建从Azure DevOps向Azure App Service发布代码的环境,由于步骤比较繁琐,每次都会忘记其中几个步骤,所以在此总结一下,已备后续再次使用. Azure DevOps和Azure App Service Azure DevOps Azure DevOps