OpenAPI 规范 (OAS) 定义了一个标准、与语言无关的 HTTP API 接口。这使得人类和计算机无需访问源代码、文档或通过网络流量检查，即可发现和理解服务的功能。当正确定义后，消费者只需最少的实现逻辑即可理解并与远程服务交互。
OpenAPI 定义随后可用于文档生成工具以显示 API、代码生成工具以生成各种编程语言的服务器和客户端、测试工具以及许多其他用例。
我直接从其规范中提取了上述关于 OpenAPI 是什么的描述。如果您是那些在Swagger Editor中手动编写 OpenAPI 定义的人，那么本文就是为您而写的。
几年前，我曾在一家名为 Ubiquiti Inc 的公司工作。我们当时生产带有嵌入式用户界面的优秀无线硬件解决方案。我很幸运能在 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: https:///
definition-file: examples/openapi-2-0.yaml
如果您的 OpenAPI 定义验证成功，您将看到以下内容。
如果您的 OpenAPI 定义包含错误，您将看到以下内容。
未来
在实现过程中，我发现了此 action 可以受益的其他功能。为了不扩展第一个版本的实现范围，我决定不实现这些功能，而是先记录它们，稍后再实现。这些功能包括：
我认为最有趣的是忽略错误的机制。在 https://editor.swagger.io/ 中验证 OpenAPI 定义时，其包含错误的情况非常普遍。有些情况下，作者对这些错误无能为力，而且这些错误是已知且被忽略的。这将为这种用例打开大门，我相信这种情况相当普遍。
我希望 swagger-editor-validate 能成为所有使用 Swagger Editor 编辑 OpenAPI 定义的人的便捷工具。我知道它对我以前在 Ubiquiti Inc 的团队会非常有用 ;]