首页 博客 集成您的 Slack...

将您的 Slack 与 Swagger 集成！

Lorinda Brandon
  2015 年 8 月 20 日

作者： Will Witman 和 Marsh Gardiner

Slack，当今最热门的初创公司之一，是一个用于团队沟通的消息应用程序。Slack 如此受欢迎的原因之一是，许多外部服务，如 GitHub、Google Drive、Heroku、Jira 和许多其他服务都作为开箱即用的集成出现。但一个特别好的功能是创建您自己的自定义功能非常容易。

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

alt text

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

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

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

alt text

我们将在本地运行和测试 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 团队菜单中，选择 配置集成。alt text

  3. 向下滚动到 DYI 集成和自定义，然后单击 传入 WebHook。

  4. 在 发布到频道 中，选择要将 API 响应发布到的频道。换句话说，每当有人调用 Ticker-bot 时，股票价格都会发布到此频道供所有人查看。

  5. 单击 添加传入 WebHook 集成。

  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！

请记住，使用传入 WebHook 集成，目的是将消息从另一个服务发送到 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 会话中获得格式良好的响应，如下所示

    alt text

发生了什么？

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

下一步是什么？

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

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

因此，你可以在 Slack 中执行如下操作...

/reverse 敏捷的棕色狐狸跳过了懒惰的狗

alt text

...然后 Slack 会返回反转的字母

alt text

您可能还喜欢