AngularJSAzure 应用服务中之 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
    检索首届数据。

再次多读书资料

相关文章