本篇文章将演示如何使用 Swagger 定义创建 Express 框架 Node.js REST API，并在 Azure 上将其部署为 API 应用。 使用命令行工具创建应用，使用 Azure CLI 配置资源，并使用 Git 部署该应用。 完成后，即可获得一个在 Azure 上运行的有效示例 REST API。
先决条件 Git Node.js 和 NPM Note 如果没有 Azure 订阅，可在开始前创建一个试用帐户。 如果选择在本地安装并使用 CLI，本主题要求运行 Azure CLI 2.0 版或更高版本。 运行 az --version 即可查找版本。 如果需要进行安装或升级，请参阅安装 Azure CLI 2.0。 准备环境 1.在终端窗口中，运行以下命令，将示例克隆到本地计算机。 git clone https://github.com/Azure-Samples/app-service-api-node-contact-list
2.切换到包含示例代码的目录。 cd app-service-api-node-contact-list
3.在本地计算机上安装 Swaggerize。 Swaggerize 是一种工具，用于从 Swagger 定义生成用于 REST API 的 Node.js 代码。 npm install -g yo npm install -g generator-swaggerize
生成 Node.js 代码 本教程部分为 API 开发工作流建模，将在其中先创建 Swagger 元数据，然后以此创建（自动生成）API 服务器代码基架。 将目录更改为 start 文件夹，然后运行 yo swaggerize。 Swaggerize 从 api.json 中的 Swagger 定义创建用于 API 的 Node.js 项目。 cd start yo swaggerize --apiPath api.json --framework express
当 Swaggerize 请求提供项目名称时，请使用 ContactList。 Swaggerize Generator Tell us a bit about your application ? What would you like to call this project: ContactList ? Your name: Francis Totten ? Your github user name: fabfrank ? Your email: [email protected]
自定义项目代码 1.将 lib 文件夹复制到 yo swaggerize 创建的 ContactList 文件夹，然后将目录更改为 ContactList。 cp -r lib/ ContactList/ cd ContactList
2.安装 jsonpath 和 swaggerize-ui NPM 模块。 npm install --save jsonpath swaggerize-ui
3.将 handlers/contacts.js 中的代码替换为以下代码： 'use strict';
var repository = require('../lib/contactRepository');
module.exports = { get: function contacts_get(req, res) { res.json(repository.all()) } }; 此代码使用 lib/contactRepository.js 提供的 lib/contacts.json 中存储的 JSON 数据。 新的 contacts.js 代码将存储库中的所有联系人返回为 JSON 有效负载形式。
4.将 handlers/contacts/{id}.js 文件中的代码替换为以下代码： 'use strict';
var repository = require('../../lib/contactRepository');
module.exports = {
get: function contacts_get(req, res) {
res.json(repository.get(req.params['id']));
}
};
此代码允许使用路径变量仅返回具有给定 ID 的联系人。
5.将 server.js 中的代码替换为以下代码： 'use strict';
var port = process.env.PORT || 8000;
var http = require('http'); var express = require('express'); var bodyParser = require('body-parser'); var swaggerize = require('swaggerize-express'); var swaggerUi = require('swaggerize-ui'); var path = require('path');
var app = express();
var server = http.createServer(app);
app.use(bodyParser.json());
app.use(swaggerize({ api: path.resolve('./config/swagger.json'), handlers: path.resolve('./handlers'), docspath: '/swagger' }));
// change four
app.use('/docs', swaggerUi({
docs: '/swagger'
}));
server.listen(port, function () { }); 此代码进行了一些小的更改，可与 Azure 应用服务配合使用，并公开一个用于 API 的交互式 Web 界面。
在本地测试 API 1.启动 Node.js 应用 npm start
2.浏览到 http://localhost:8000/contacts， 查看整个联系人列表的 JSON。 { "id": 1, "name": "Barney Poland", "email": "[email protected]" }, { "id": 2, "name": "Lacy Barrera", "email": "[email protected]" }, { "id": 3, "name": "Lora Riggs", "email": "[email protected]" }
3.浏览到 http://localhost:8000/contacts/2， 查看具有两个 id 中其中一个的联系人。 { "id": 2, "name": "Lacy Barrera", "email": "[email protected]" }
4.在 http://localhost:8000/docs 使用 Swagger Web 界面测试 API。
创建 API 应用 本部分将使用 Azure CLI 2.0 创建在 Azure 应用服务上托管 API 的资源。 在 Azure 中国区使用 Azure CLI 2.0 之前，请先运行 az cloud set -n AzureChinaCloud 来改变云环境。如果想切回国际版 Azure，请再次运行 az cloud set -n AzureCloud。
1.使用 az login 命令登录到 Azure 订阅，并按照屏幕上的说明进行操作。 az login
2.如果有多个 Azure 订阅，则可将默认订阅更改为所需订阅。 az account set --subscription
3.使用 az group create 命令创建资源组。 资源组是在其中部署和管理 Azure 资源（例如 Web 应用、数据库和存储帐户）的逻辑容器。 以下示例在“chinanorth”位置创建名为“myResourceGroup”的资源组。 az group create --name myResourceGroup --location chinanorth 若要查看可用位置，请运行 az appservice list-locations 命令。 通常在附近的区域中创建资源。
4.使用 az appservice plan create 命令创建应用服务计划。 以下示例在免费定价层中创建名为 myAppServicePlan 的应用服务计划： az appservice plan create --name myAppServicePlan --resource-group myResourceGroup --sku FREE 创建应用服务计划后，Azure CLI 将显示类似于以下示例的信息： { "adminSiteName": null, "appServicePlanName": "myAppServicePlan", "geoRegion": "China North", "hostingEnvironmentProfile": null, "id": "/subscriptions/0000-0000/resourceGroups/myResourceGroup/providers/Microsoft.Web/serverfarms/myAppServicePlan", "kind": "app", "location": "China North", "maximumNumberOfWorkers": 1, "name": "myAppServicePlan", < JSON data removed for brevity. > "targetWorkerSizeId": 0, "type": "Microsoft.Web/serverfarms", "workerTierName": null }
5.使用 az webapp create 命令在 myAppServicePlan 应用服务计划中创建 API 应用。 该 Web 应用为 API 提供托管空间，并提供一个 URL 用于查看已部署的应用。 在以下命令中，将 <app_name> 替换为唯一名称。 如果 <app_name> 不是唯一名称，将收到错误消息“具有给定名称 <app_name> 的网站已存在”。 Web 应用的默认 URL 为 https://<app_name>.chinacloudsites.cn。 az webapp create --name <app_name> --resource-group myResourceGroup --plan myAppServicePlan 创建 Web 应用后，Azure CLI 将显示类似于以下示例的信息： { "availabilityState": "Normal", "clientAffinityEnabled": true, "clientCertEnabled": false, "cloningInfo": null, "containerSize": 0, "dailyMemoryTimeQuota": 0, "defaultHostName": "<app_name>.chinacloudsites.cn", "enabled": true, "enabledHostNames": [ "<app_name>.chinacloudsites.cn", "<app_name>.scm.chinacloudsites.cn" ], "gatewaySiteName": null, "hostNameSslStates": [ { "hostType": "Standard", "name": "<app_name>.chinacloudsites.cn", "sslState": "Disabled", "thumbprint": null, "toUpdate": null, "virtualIp": null } < JSON data removed for brevity. > }