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

Note

若要将 Visual Studio 连接到 Azure 中国区,可按选取 Visual Studio 2015
连接中国区
Azure
中的表达操作。

若果接纳的是 Visual Studio 2015 Update 2
或更高版本,可以依据以下图片中的表明,选中“启用隔离的 Azure Active
Directory 配置”选项。

AngularJS 1

假设选取的是 Visual Studio 2017,可按 应用 Visual Studio 2017
连接中国区
Azure
中的表达操作。

  • 什么样通过 Visual Studio 2015 中的内置工具在 Azure
    应用服务中创制和配置 API
    应用
  • 何以选拔 Swashbuckle NuGet 包动态生成 Swagger API
    元数据,以便自动举行 API 发现。
  • 如何使用 Swagger API 元数据自动生成 API 应用的客户端代码。

动用 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
    项目)设置为启动项目。

    AngularJS 2

  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 文件。

    AngularJS 3

    假定利用的是 Chrome、Firefox 或 Edge,浏览器将在浏览器窗口中突显JSON。差其他浏览器有分歧的 JSON
    处理方式,由此浏览器窗口看起来也许与示范相差很大。

    AngularJS 4

    以下示例彰显了 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”查看可用方法。

    AngularJS 5

  9. 单击列表中的第三个“Get”按钮。

  10. 在“参数”部分中,输入星号作为 owner 参数的值,然后单击“试用”。

    在继续教程中添加身份验证时,中间层将为数据层提供实际的用户
    ID。现在,当应用程序在未启用身份验证的场合下运作时,所有职务皆以星号作为其主人
    ID。

    AngularJS 6

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

    AngularJS 7

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

    单击模型架构会预先填充输入框,可以在该框中指定 Post
    方法的参数值。(固然那不适用于 Internet
    Explorer,请使用不一致的浏览器或在下一步骤中手动输入参数值。)

    AngularJS 8

  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
    项目,然后单击“宣布”。

    AngularJS 9

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

    AngularJS 10

  3. 如若没有登录,请登录到 Azure 帐户;若是证据已过期,请刷新凭据。

  4. 在“应用服务”对话框中,拔取要运用的 Azure 订阅,然后单击“添加”。

    AngularJS 11

    那时将显得“创设应用服务”对话框的“托管”选项卡。

    出于配备的是已设置 Swashbuckle 的 Web API 项目,由此 Visual Studio
    如果要开创 API 应用。“API
    应用名称”标题提出了那或多或少,别的,从“更改项目”下拉列表已安装为“API
    应用”也能见到那或多或少。

    AngularJS 12

  5. 输入在 chinacloudsites.cn 域中绝无仅有的 API 应用名称。能够承受
    Visual Studio 指出的默许名称。

    比方输入的称呼已被运用,左边会冒出紫色惊叹号。

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

  6. 在“资源组”下拉列表中单击“新建”,然后输入“ToDoListGroup”或任何喜欢的名号。

    资源组是 Azure 资源的汇集,例如 API 应用、数据库、VM
    等等。在本教程中,最好创立新的资源组,因为这么可以因而一个步骤轻松删除针对本教程成立的有所
    Azure 资源。

    动用此框能够选取现有资源组,或通过键入与订阅中其余现有资源组分歧的名目,来成立新资源组。

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

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

    AngularJS 13

    以下步骤为新资源组创设应用服务安顿。应用服务陈设指定 API
    应用运行所在的盘算资源。例如,要是你挑选免费层,则 API
    应用程序将在共享 VM 上运行;即使您选取一些付费层,则它在专用 VM
    上运行。有关应用服务布置的新闻,请参阅应用服务布置概述

  8. 在“配置应用服务安插”对话框中,输入“ToDoListPlan”或其余喜欢的称呼。

  9. 在“地点”下拉列表中,选用最靠近的职位。

    此设置指定你的采纳将在哪些 Azure
    数据主导运转。拔取最靠近的职位,尽量缩小延迟

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

    对于本学科,免费定价层即可提供丰硕的性能。

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

    AngularJS 14

  12. 在“创设应用服务”对话框中,单击“创立”。

    AngularJS 15

    Visual Studio 将创设 API 应用,以及包罗 API
    应用全体所需安装的揭橥配置文件。然后,将开辟“发布Web”向导来布置项目。

    打开的“发表 Web”向导最初突显“连接”选项卡(如下所示)。

    在“连接”选项卡上,“服务器”和“站点名称”设置指向 API
    应用。“用户名”和“密码”是 Azure 创建的配置凭据。陈设后,Visual Studio
    将在浏览器中开拓目标 URL(这是目标 URL 的绝无仅有用途)。

  13. 单击“下一步”。

    AngularJS 16

    下一个选项卡是“设置”选项卡(如下所示)。可以在此地更改生成配置选项卡,安插用于长途调试的调剂生成。该选项卡还提供了七个“文件表露选项”:

    • 除去目标处的别样文件
    • 在公布时期预编译
    • 从 App_Data 文件夹中革除文件

    在本教程中,不要求拔取那几个采纳。有关这么些选取的成效的辨证,请参阅
    How to: Deploy a Web Project Using One-Click Publish in Visual
    Studio
    (咋样:在
    Visual Studio 中使用一键式发布来布置 Web 项目)。

  14. 单击“下一步”。

    AngularJS 17

    接下去是“预览”选项卡(如下所示),用于查看哪些文件即将从品种复制到
    API 应用。借使要将项目布局到前边已安插到的 API
    应用,则只会复制已更改的文件。如果想要查看要复制的项列表,请单击“初阶预览”按钮。

  15. 单击“发布”。

    AngularJS 18

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

    AngularJS 19

    AngularJS 20

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

    浏览器将体现前面出现的均等 Swagger UI,但该 UI
    现在在云中运转。尝试选取 Get 方法,会发觉已回到到默许的 2
    个待办事项。后边所做的更动已保存在当地电脑的内存中。

  17. 打开 Azure 门户

    Azure 门户是用以管理 Azure 资源(例如 API 应用)的 Web 界面。

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

    AngularJS 21

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

    AngularJS 22

    将打开四个边栏选项卡。其中一个边栏选项卡包涵 API
    应用的概述,另一个饱含可以查阅和改动的一长串设置。

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

    AngularJS 23

    采纳“API 定义”边栏选项卡可以指定以 JSON 格式再次来到 Swagger 2.0
    元数据的 URL。当 Visual Studio 成立 API 应用时,会将 API 定义 URL
    设置为眼前所示的 Swashbuckle 生成的元数据默许值,即 API 应用的基 URL
    加上 /swagger/docs/v1

    AngularJS 24

    选料要为其变动客户端代码的 API 应用时,Visual Studio 将随后 URL
    检索元数据。

更加多学学资料

先决条件

  • 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(Service) Tools v2.9.1”或更高版本。

      AngularJS 25

      ##### Note

      基于统计机上已有 SDK 着重项数据的例外,安装 SDK
      可能耗时较长,从几分钟到半小时或更长日子不等。

演示应用程序概述

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

AngularJS 26

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

AngularJS 27

Visual Studio 解决方案包括多少个品类:

AngularJS 28

  • ToDoListAngular – 前端:用于调用中间层的 AngularJS SPA。

  • ToDoListAPI – 中间层:调用数据层,对待工作项实施 CRUD 操作的
    ASP.NET Web API 项目。

  • ToDoListDataAPI – 数据层:对待工作项实施 CRUD 操作的 ASP.NET Web
    API 项目。

三层种类布局是足以行使 API
应用完成的有余系统布局之一,此处仅用它来展开出现说法。每一层中的代码尽可能以最简便的办法来演示
API 应用功效;例如,数据层使用服务器内存而不是数据库作为持久性机制。

成功本课程后,将创造三个在云中应用服务 API 应用中启动并运行的 Web API
项目。

本体系教程的下一篇小说会将 SPA 前端安排到云中。

下载示例应用程序

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

    可以单击“下载 ZIP”按钮,或克隆本地电脑上的存储库。

  2. 在 Visual Studio 2015 或 2013 中开辟 ToDoList 解决方案。

    1. 亟需信任每个解决方案。AngularJS 29
  3. 转变解决方案 (CTRL + SHIFT + B) 以平复 NuGet 包。

    一经要在安排应用程序以前先查看应用程序的周转境况,可以在地面运行此应用程序。确保
    ToDoListDataAPI 是开行项目,然后运行解决方案。应该会在浏览器中看出
    HTTP 403 错误。

相关文章