将您的 Slack 与 Swagger 集成！

作者： Will Witman 和 Marsh Gardiner

Slack，当今最热门的创业公司之一，是一款用于团队沟通的消息应用。Slack 如此受欢迎的一个原因是，许多外部服务（如 GitHub、Google Drive、Heroku、Jira 等）都提供开箱即用的集成。但它一个非常好的功能是，创建自己的自定义功能非常容易。

今天，我们将引导您使用 swagger-node 创建自己的 Slack 集成，它使得使用 Swagger 和 Node.js 在本地构建、验证和测试 API 项目变得容易。您可以稍后将项目部署到任何支持 Node.js 的云平台。在本例中，我们将创建一个 API 来获取股票报价，然后使用 Slack 称为“Incoming WebHook”的集成，将其直接发布到 Slack 团队对话中。

此 API 的后端资源将是 /ticker，您可以通过 cURL 调用

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" https://:10010/ticker -d "text=AAPL

...并获得 Slack 中格式良好的响应，如下所示

我们将在本地运行和测试此 API；但是，它可以部署到任何支持 Node.js 的云平台，例如 Apigee、AWS 或 Heroku。

开始之前

如果您打算尝试执行下面概述的步骤，您必须是 Slack 团队的成员或创建一个新团队。无论哪种情况，您都需要拥有创建集成的权限。

从 GitHub 获取 swagger-node-slack 示例应用

为了让事情变得格外简单，您可以下载一个可用的项目

1. 从 GitHub 下载或克隆 swagger-node-slack 项目。
2. cd 进入根项目目录 swagger-node-slack。
3. 执行此命令以获取 Node.js 依赖项：npm install

构建 Ticker-bot 集成

让我们逐步了解如何将 /ticker API 与 Slack 集成。这非常容易。

首先，快速了解内部机制

让我们快速看一下 swagger-node-slack 项目。

（如果您不熟悉 swagger-node 项目结构，您可以查阅文档，如果喜欢，还可以尝试快速入门教程。）

理解 swagger-node-slack API 如何工作的关键是查看这两个文件

• ./swagger-node-slack/api/swagger/swagger.yaml -- 这是 API 的 Swagger 定义。请注意，它定义了服务的路径、操作和参数。您可以使用内置的 Swagger 编辑器通过swagger project edit 进行更改。

这些实体直接关联到相应的控制器文件，如下所述。

    ...
    paths: 
        /ticker:
        # binds app logic to a route
        x-swagger-router-controller: ticker
        post:
          description: look up a stock price
          # used as the method name of the controller
          operationId: ticker
          consumes:
            + application/x-www-form-urlencoded
          parameters:
            + $ref: "#/parameters/text"
            + $ref: "#/parameters/user_name"
            + $ref: "#/parameters/icon_url"
            + $ref: "#/parameters/icon_emoji"
            + $ref: "#/parameters/channel"
          responses:
            "200":
              description: Success
            # responses may fall through to errors
            default:
              description: Error
              schema:
                $ref: "#/definitions/ErrorResponse"
    ...

• ./swagger-node-slack/api/controllers/ticker.js -- 这是一个控制器文件。它实现了针对特定 API 路径（或路由）执行的逻辑。在 swagger.yaml 文件中，x-swagger-router-controller 属性指定了控制器文件的名称（不需要 .js）。operationId 指定了当请求 /ticker 路径时要调用的函数的名称。因此，对于此 API，当您调用 /ticker API 时，它会在名为 ticker.js 的控制器文件中执行一个名为ticker() 的函数。这是控制器代码。URL 变量的值来自 Slack。当请求到达服务器时，它会自动由 Swagger 规范分类，并且 swagger-node 项目可以轻松访问传入请求的结构。例如，要访问名为“text”的已定义参数的值，您可以使用 req.swagger.params.text.value。它在控制器代码中是这样的

  var util = require('util');
  var request = require('request');
  var googleStocks = require('google-stocks');
  module.exports = {
    ticker: ticker
  };
  //var URL = "https://hooks.slack.com/services/GET/FROM/SLACK";
  function ticker(req, res) {
      var symbol = req.swagger.params.text.value.toUpperCase();
      googleStocks.get([symbol], function(error, data) {
          console.log(symbol+": "+data[0].l);
          var text = symbol+" is now $"+data[0].l+" per share.\nThanks for asking, @"+req.swagger.params.user_name.value+"!";
          request.post({ url:URL, body:{"text":text}, json:true});
          res.status(200).type('application/json').end();
      });
  }
  

创建 Slack 集成

现在，在 Slack 端，我们需要创建和配置集成。

1. 登录您的 Slack 账户。
2. 从您的 Slack 团队菜单中，选择 配置集成。
3. 向下滚动到 DIY 集成与自定义，然后点击 Incoming WebHooks。
4. 在 发布到频道 中，选择要发布 API 响应的频道。换句话说，每当有人调用 Ticker-bot 时，股票价格就会发布到此频道供所有人查看。
5. 点击 添加 Incoming WebHooks 集成。
6. 如果您愿意，可以查看设置说明。我们主要关心的是 WebHook URL。
7. 复制 WebHook URL。提示：这是您需要添加到控制器文件的 URL。它看起来像这样：https://hooks.slack.com/services/X01234/BT1234/PSb1234abcdefghi";
8. 在 自定义名称 字段中，将默认名称更改为“Ticker-bot”。这是将出现在 Slack 帖子中的名称。
9. 使用 自定义图标 UI 选择将在 Slack 帖子中显示的表情符号。

编辑控制器

最后，让我们将该 WebHook URL 添加到 ticker.js 控制器文件。

1. 在文本编辑器中打开文件 swagger-node-slack/api/controllers/ticker.js。
2. 找到此变量并取消注释：var URL = "https://hooks.slack.com/services/GET/SLACK URL";
3. 将 URL 变量的值替换为 Webhook URL。例如（请务必使用您的 URL，而不是此示例中的 URL！）：var URL = "https://hooks.slack.com/services/X01234/BT1234/PSb1234abcdefghi";
4. 保存文件。

试试看！

使用 swagger-node 构建的项目的一个好处是，您可以在内置的 HTTP 服务器上本地构建和测试它们。让我们试试我们的新 Ticker-bot！

请记住，对于 Incoming WebHooks 集成，其思想是将消息从另一个服务发送到 Slack 频道。

1. cd 进入 swagger-node-slack 目录。
2. 如果您之前没有这样做，请执行此命令以更新 Node.js 依赖项：npm install
3. 启动项目：swagger project start
4. 在另一个终端窗口中，像这样调用 API...curl -X POST -H "Content-Type: application/x-www-form-urlencoded" https://:10010/ticker -d "text=AAPL&user_name=Will"...然后您会在 Slack 会话中收到一个格式良好的响应，如下所示

   

发生了什么？

我们已经看到使用 swagger-node 后端 API 创建 Slack WebHooks 集成命令是多么容易。该 API 将请求代理到股票价格服务，并通过 Slack WebHook 集成将响应发布回 Slack。Slack 检索到响应并将其打印到聊天窗口。

下一步是什么？

另一个很酷的 Slack 集成是“斜杠命令”。Slack 斜杠命令允许您通过直接在 Slack 对话中输入来执行函数。

如果您想查看 swagger-node 的斜杠命令示例，请跳转到 swagger-node-slack 项目，您将在那里找到本博客教程的扩展版本。斜杠命令示例构建了一个可以反转您提供的任何文本的命令。它包括令牌验证以及将您的 API 部署到云的步骤。

所以，您可以在 Slack 中执行以下操作...

/reverse The quick brown fox jumps over the lazy dog

... 然后 Slack 将字母反向返回