首页 博客 如何验证...

如何在 Swagger Editor 中使用 GitHub Actions 验证 OpenAPI 定义

Vladimir Gorej
  2021 年 3 月 25 日

OpenAPI 规范 (OAS) 定义了 HTTP API 的标准、与语言无关的接口。这允许人类和计算机在不访问源代码、文档或通过网络流量检查的情况下发现和理解服务的功能。如果定义正确，消费者可以使用最少的实现逻辑来理解远程服务并与之交互。

然后，文档生成工具可以使用 OpenAPI 定义来显示 API，代码生成工具可以生成各种编程语言的服务器和客户端，测试工具以及许多其他用例。

我直接从其规范中获取了上述关于 OpenAPI 是什么的描述。如果您是那些在Swagger Editor中手动编写 OpenAPI 定义的人之一，那么这篇文章就是为您而写的。

几年前，我曾在一家名为Ubiquiti Inc的公司工作。我们正在生产具有嵌入式 UI 的出色的无线硬件解决方案。我很幸运在名为UNMS的跨硬件配置系统正在架构和开发时加入了该公司。系统的后端部分由前端层使用的庞大的REST API层组成。我们使用了设计优先方法来生成 API。

这种方法的工作流程包括以下步骤

  • 使用 Swagger Editor 在 OpenAPI 2.0 定义中创建更改
  • 发布者：发布一个GitHub 拉取请求，供团队审查新的 API 端点可能的外观
  • 审查者：将拉取请求中的 OpenAPI 定义粘贴到 Swagger Editor 中，以查看是否引入了错误
  • 合并拉取请求
  • 实现 OpenAPI 定义中定义的实际 REST API

今天我将立即考虑如何自动化此工作流程并让持续集成为我们工作。不幸的是，当时我对 CI/CD 管道的了解有限，并且我没有完全意识到 CI/CD 提供的优势和价值。

从那以后已经过了一段时间。我做了功课，彻底研究了 CI/CD 主题。我成了 GitHub Actions 和自动化 的忠实粉丝。让我们尝试使用GitHub Actions自动化上述工作流程。

技术设计

我们需要生成一个 GitHub Action，该操作使用 Swagger Editor 验证作为该操作的参数提供的 OpenAPI 定义。

在 GitHub Action 中使用 Swagger Editor 可以通过两种方式实现：使用 swaggerapi/swagger-editor 镜像在 docker 容器中运行它，或直接使用 https://editor.swagger.io/。现在我们已经运行了 Swagger Editor，我们使用 Puppeteer 打开 Chromium 浏览器的无头版本，将 OpenAPI 定义粘贴到 Swagger Editor 中，并等待它呈现错误（如果定义有效，则不会呈现错误）。使用 Puppeteer 从 Swagger Editor 读取错误，并通过 GitHub Actions API 表示它们。如果文档有效且不包含错误，则 GitHub Action 将报告失败，否则将报告成功。

为什么要使用 Swagger Editor 而不仅仅是 JSON Schema 验证？嗯，Swagger Editor 在 JSON Schema 验证之上添加了它自己额外的错误识别层。不幸的是，此附加层与 Swagger Editor 代码紧密耦合，使用它的最简单方法是通过在浏览器中运行 Swagger Editor 来使用它。

实现

实现并不像我预期的那么简单。但我仍然设法根据前面提到的技术设计及其所有要求实现了此 GitHub Action。我将其称为swagger-editor-validate。

用法

如何使用此 GitHub Action 有两种主要用例，但它们都使用了您的定义文件位于您的 GitHub 存储库中的事实。您只需要提供一个文件系统路径即可。

公共用例

如果您可以访问互联网，并且不介意此 GitHub Action 将您的 OpenAPI 定义发送到https://editor.swagger.io/进行验证，则使用此工作流程。

on: [push]


jobs:
  test_swagger_editor_validator_remote:
    runs-on: ubuntu-latest
    name: Swagger Editor Validator Remote


    steps:
      - uses: actions/checkout@v2
      - name: Validate OpenAPI definition
        uses: char0n/swagger-editor-validate@v1
        with:
          definition-file: examples/openapi-2-0.yaml

私有用例

如果您想保持完全隐私并且您的 OpenAPI 定义可能包含敏感信息，请使用以下工作流程。该工作流程使用 Swagger-editor docker 镜像，该镜像作为工作流程的服务运行。

on: [push]


jobs:
  test_swagger_editor_validator_service:
    runs-on: ubuntu-latest
    name: Swagger Editor Validator Service


    # Service containers to run with `runner-job`
    services:
      # Label used to access the service container
      swagger-editor:
        # Docker Hub image
        image: swaggerapi/swagger-editor
        ports:
          # Maps port 8080 on service container to the host 80
          - 80:8080


    steps:
      - uses: actions/checkout@v2
      - name: Validate OpenAPI definition
        uses: char0n/swagger-editor-validate@v1
        with:
          swagger-editor-url: http://localhost/
          definition-file: examples/openapi-2-0.yaml

如果您的 OpenAPI 定义验证成功，您将看到以下内容。

如果您的 OpenAPI 定义包含错误，您将看到以下内容。

未来

在实现过程中，我确定了此操作可以从中受益的其他功能。为了不扩展第一版的实现范围，我决定不实现这些功能，而是记录它们并在以后实现它们。这些功能包括

我认为最有趣的是忽略错误的机制。在https://editor.swagger.io/中验证时，OpenAPI 定义包含错误是很常见的。在某些情况下，作者对这些错误无能为力，并且这些错误是已知的并被忽略。这将为这样的用例打开大门，我确信这很常见。

我希望swagger-editor-validate将成为任何使用 Swagger Editor 编辑 OpenAPI 定义的人的便捷工具。我知道它将对我在 Ubiquiti Inc 的老团队有所帮助 ;]

您可能还喜欢