vacuum

vacuum

高性能OpenAPI和Swagger规范分析工具

vacuum是一款Go语言开发的高性能OpenAPI规范分析工具。支持OpenAPI 2.0和3.0+版本,兼容YAML和JSON格式。提供命令行界面、交互式控制台和HTML报告,可快速分析大型API规范并给出修复建议。兼容Spectral规则集,支持自定义JavaScript函数和OWASP API安全规则。

vacuumOpenAPISwaggerlintergolangGithub开源项目

logo

vacuum - 世界上最快的OpenAPI和Swagger检查工具。

build Go Report Card discord Docs GitHub downloads npm Docker Pulls Mentioned in Awesome Go

一个超级快速、轻量级的OpenAPI检查和质量检查工具,用golang编写,灵感来自Spectral

它还兼容现有的Spectral规则集。

使用homebrewtap安装

brew install daveshanley/vacuum/vacuum

使用npm安装

npm i -g @quobix/vacuum

使用yarn安装

yarn global add @quobix/vacuum

使用curl安装

curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh

使用Docker安装

镜像可在以下地址获取:https://hub.docker.com/r/dshanley/vacuum

docker pull dshanley/vacuum

要运行,将当前工作目录挂载到容器并使用规范的相对路径,如下所示

docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>

或者,你可以从Github packages获取。 要这样做,请在上述命令中将dshanley/vacuum替换为ghcr.io/daveshanley/vacuum

使用Go运行

如果你安装了go >= 1.16,你可以使用go run来构建和运行它:

go run github.com/daveshanley/vacuum@latest lint <your-openapi-spec.yaml>

赞助商

如果你的公司正在使用vacuum,请考虑支持这个项目, 就像我们非常友善的赞助商:

<a href="https://speakeasyapi.dev/?utm_source=vacuum+repo&utm_medium=github+sponsorship"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/sponsors/speakeasy-github-sponsor-dark.svg"> <img alt="speakeasy'" src="https://yellow-cdn.veclightyear.com/2b54e442/ccf0a797-700c-43dd-8e20-ca2dd5c7af97.svg"> </picture> </a>

Speakeasy

<a href="https://scalar.com"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/sponsors/scalar-dark.png"> <img alt="scalar" src="https://yellow-cdn.veclightyear.com/2b54e442/442be1ba-57ba-4c58-b4b4-b0473a627f5d.png"> </picture> </a>

scalar


来和我们聊天

需要帮助?有问题?想分享你的工作?加入我们的discord来打个招呼!

文档

🔥 v0.12+新功能 🔥 : 核心函数支持JSON路径

现在所有核心函数都为每个检查结果返回正确和准确的JSON路径。以前这是完全不可能的, 但通过一些巧妙的工程,我们实现了它。这是一个小变化,但影响巨大。

这个功能在OpenAPI函数上已经存在一段时间了,但核心函数之前没有比较。 但现在不再如此!核心函数已经加入了派对。

lint命令现在有一个新的--no-clip标志。这可以防止消息/路径被截断。


v0.11+: 忽略检查错误/违规。

v0.11引入了忽略特定检查错误的能力。这在你想为现有生产API实施新规则时非常有用。 在某些情况下,纠正检查错误可能会导致破坏性变更。

有一种忽略这些错误的方法可以让你为新API实施新规则,同时保持现有API的向后兼容性。

了解更多关于忽略违规的信息


v0.10+ : 质量发布

v0.10是一个质量发布,对规则模式、函数名称等进行了多项修复和改进。 vacuum现在为The OpenAPI doctor提供支持。为了实现正确的规则集管理和自动化, 一些函数被重命名,接口被升级,规则函数模式现在更准确。

这对于任何使用vacuum作为库并使用自定义规则的人来说是一个破坏性变更。


v0.9+ : 内置语言服务器

现在有一个新的命令language-server。这会将vacuum作为LSP兼容的语言服务器启动。在你 喜欢的IDE中运行vacuum,实时获取检查和验证。

将支持任何LSP兼容的编辑器,如VSCode、Sublime、vim等。

安装VSCode扩展 了解更多关于language-server命令


v0.8+ : OpenAPI打包工具

现在有一个新的命令bundle,它会将OpenAPI文件的所有外部引用打包成一个单一文件。

了解更多关于bundle命令

现在有一个新的检查规则oas-schema-check,它会对OpenAPI文件中的所有模式执行类型检查和验证。 它在推荐的规则集中默认启用。

oas-schema-check规则文档


v0.7+ : 困难模式

想用最严格的规则集检查你的规范吗?现在你可以了!使用-z / --hard-mode标志来启用


v0.6+ : 现在可以使用可共享/分布式规则集

想要共享/扩展/分发你自己的规则集吗?现在你可以了!

了解更多关于可共享规则集


v0.5+ : lint命令现在可以进行多文件检查

想一次检查多个文件吗?现在你可以了!

vacuum lint file1.json path/to/file2.yaml file3.json

想处理大量文件吗?使用glob模式!

vacuum lint some/path/**/*.yaml

v0.3+: 自定义JavaScript函数现在可以开箱即用。

用JavaScript编写自定义函数,并在任何规则集中使用它们。不再需要 编译golang代码来扩展vacuum了!

了解更多关于构建自定义JavaScript函数


v0.2+: OWASP API规则现在可以开箱即用。

了解更多关于启用OWASP API规则


快速入门指南 🚀

https://quobix.com/vacuum查看所有文档


vacuum可以在毫秒内吸走5mb OpenAPI规范中的所有lint。

设计用于可靠地检查OpenAPI规范,非常非常快速。包括非常大的规范。当作为API使用时,Spectral可能会相当慢, 并且不能适应企业应用程序的规模。

vacuum会告诉你你的规范有什么问题,为什么,在哪里以及如何修复它。

vacuum将在规模上工作,并被设计为CLI(带有web或控制台UI)和一个可以被其他应用程序使用的库。

仪表板

vacuum带有一个交互式仪表板(vacuum dashboard <your-openapi-spec.yaml>),允许你在控制台中探索 规则和违规情况,而无需滚动浏览数千个结果。 真空仪表板

HTML报告

vacuum可以生成易于导航和理解的HTML报告。像仪表板一样,您可以在浏览器中探索违反的规则和违规情况。

无需外部依赖,HTML报告可以完全离线运行。

vacuum html报告


支持OpenAPI版本2(Swagger)和版本3+

您可以使用YAMLJSON,vacuum支持这两种格式。

将vacuum与pre-commit一起使用

Vacuum可以与pre-commit一起使用。

要做到这一点,请将以下内容添加到您的.pre-commit-config.yaml中:

repos: - repo: https://github.com/daveshanley/vacuum rev: # 从该仓库中选择一个标签或提交哈希,参见 https://github.com/daveshanley/vacuum/releases hooks: - id: vacuum

有关钩子使用的选项和默认检查的文件的详细信息,请参阅此处的钩子定义

如果您的仓库中没有文件名或多个文件名与钩子定义中的默认files模式匹配,则需要在您的配置中覆盖该模式,以便一次只匹配一个确切的文件名进行检查。 要检查多个文件,请使用适当的覆盖多次指定钩子。

构建交互式HTML报告

./vacuum html-report <your-openapi-spec.yaml | vacuum-report.json.gz> <report-name.html>

您可以将report-name.html替换为您选择的文件名。在您喜欢的浏览器中打开报告并探索结果。

查看完整的检查报告

./vacuum lint -d <your-openapi-spec.yaml>

一次检查多个文件

./vacuum lint -d <spec1.yaml> <spec2.yaml> <spec3.yaml>

使用glob模式检查多个文件

./vacuum lint -d some/path/**/*.yaml

查看带有内联代码片段的完整检查报告

./vacuum lint -d -s <your-openapi-spec.yaml>

只查看检查错误

./vacuum lint -d -e <your-openapi-spec.yaml>

只查看特定类别的报告

./vacuum lint -d -c schemas <your-openapi-spec.yaml>

这里的选项有:

  • examples
  • operations
  • information
  • descriptions
  • schemas
  • security
  • tags
  • validation
  • owasp

生成Spectral兼容的报告

如果您已经在使用Spectral JSON报告,并且想要改用vacuum,请使用spectral-report命令

./vacuum spectral-report <your-openapi-spec.yaml> <report-output-name.json>

报告文件名是_可选的_。默认的报告输出名称是vacuum-spectral-report.json

生成vacuum报告

Vacuum报告是规范检查报告的完整时间快照。这些报告可以通过vacuum"回放"。 使用dashboardhtml-report命令来"回放"报告,并像生成报告时那样探索结果。

./vacuum report -c <your-openapi-spec.yaml> <report-prefix>

报告的默认名称将是vacuum-report-MM-DD-YY-HH_MM_SS.json。您可以通过提供第二个参数来更改report命令的前缀。

理想情况下,您应该使用-c压缩报告。这会显著减小文件大小。vacuum在读取时会自动识别压缩的报告文件并处理它。

使用压缩时,文件名将是vacuum-report-MM-DD-YY-HH_MM_SS.json.gz。vacuum内部使用gzip。

忽略特定的检查错误

您可以通过为lintreport命令提供--ignore-file参数来忽略特定的检查错误。

./vacuum lint --ignore-file <path-to-ignore-file.yaml> -d <your-openapi-spec.yaml>
./vacuum report --ignore-file <path-to-ignore-file.yaml> -c <your-openapi-spec.yaml> <report-prefix>

ignore-file应指向一个.yaml文件,其中包含vacuum要忽略的错误列表。yaml文件的结构如下:

<rule-id-1>:
  - <json_path_to_error_or_warning_1>
  - <json_path_to_error_or_warning_2>
<rule-id-2>:
  - <json_path_to_error_or_warning_1>
  - <json_path_to_error_or_warning_2>
  ...

忽略错误对于在现有生产API中实施新规则很有用。在某些情况下, 纠正检查错误可能会导致破坏性更改。有一种方法可以忽略这些错误,允许您为新API实施 新规则,同时保持现有API的向后兼容性。


尝试仪表板

这是vacuum的一个早期但可用的控制台UI。代码还不是很好,需要大量清理,但 如果您有兴趣了解进展情况,它是可用的。

./vacuum dashboard <your-openapi-spec.yaml | vacuum-report.json.gz>

提供您自己的Spectral兼容规则集

如果您已经在使用Spectral,并且有自己的自定义规则集, 那么您可以将其与vacuum一起使用!

lintdashboardspectral-report命令都接受-r--ruleset标志,定义规则集文件的路径。

以下是一些您可以尝试的示例

所有规则关闭

./vacuum lint -r rulesets/examples/norules-ruleset.yaml <your-openapi-spec.yaml>

仅推荐规则

./vacuum lint -r rulesets/examples/recommended-ruleset.yaml <your-openapi-spec.yaml>

仅启用特定规则

./vacuum lint -r rulesets/examples/specific-ruleset.yaml <your-openapi-spec.yaml>

自定义规则

./vacuum lint -r rulesets/examples/custom-ruleset.yaml <your-openapi-spec.yaml>

所有规则,全部启用!

./vacuum lint -r rulesets/examples/all-ruleset.yaml <your-openapi-spec.yaml>

配置

文件

您可以使用名为vacuum.conf.yaml的配置文件来配置vacuum

默认情况下,vacuum在以下目录中搜索此文件

  1. 工作目录
  2. $XDG_CONFIG_HOME
  3. ${HOME}/.config

您还可以使用--config标志指定文件路径

全局标志配置为顶级节点

time: true base: 'http://example.com' ...

特定于命令的标志在命令名称的节点下配置

... lint: silent: true ...

环境变量

您可以使用环境变量以VACUUM_<flag>的形式配置全局vacuum标志

如果标志中包含-,请替换为_

Logo地鼠是修改的,原始来自egonelbre

编辑推荐精选

AEE

AEE

AI Excel全自动制表工具

AEE 在线 AI 全自动 Excel 编辑器,提供智能录入、自动公式、数据整理、图表生成等功能,高效处理 Excel 任务,提升办公效率。支持自动高亮数据、批量计算、不规则数据录入,适用于企业、教育、金融等多场景。

UI-TARS-desktop

UI-TARS-desktop

基于 UI-TARS 视觉语言模型的桌面应用,可通过自然语言控制计算机进行多模态操作。

UI-TARS-desktop 是一款功能强大的桌面应用,基于 UI-TARS(视觉语言模型)构建。它具备自然语言控制、截图与视觉识别、精确的鼠标键盘控制等功能,支持跨平台使用(Windows/MacOS),能提供实时反馈和状态显示,且数据完全本地处理,保障隐私安全。该应用集成了多种大语言模型和搜索方式,还可进行文件系统操作。适用于需要智能交互和自动化任务的场景,如信息检索、文件管理等。其提供了详细的文档,包括快速启动、部署、贡献指南和 SDK 使用说明等,方便开发者使用和扩展。

Wan2.1

Wan2.1

开源且先进的大规模视频生成模型项目

Wan2.1 是一个开源且先进的大规模视频生成模型项目,支持文本到图像、文本到视频、图像到视频等多种生成任务。它具备丰富的配置选项,可调整分辨率、扩散步数等参数,还能对提示词进行增强。使用了多种先进技术和工具,在视频和图像生成领域具有广泛应用前景,适合研究人员和开发者使用。

爱图表

爱图表

全流程 AI 驱动的数据可视化工具,助力用户轻松创作高颜值图表

爱图表(aitubiao.com)就是AI图表,是由镝数科技推出的一款创新型智能数据可视化平台,专注于为用户提供便捷的图表生成、数据分析和报告撰写服务。爱图表是中国首个在图表场景接入DeepSeek的产品。通过接入前沿的DeepSeek系列AI模型,爱图表结合强大的数据处理能力与智能化功能,致力于帮助职场人士高效处理和表达数据,提升工作效率和报告质量。

Qwen2.5-VL

Qwen2.5-VL

一款强大的视觉语言模型,支持图像和视频输入

Qwen2.5-VL 是一款强大的视觉语言模型,支持图像和视频输入,可用于多种场景,如商品特点总结、图像文字识别等。项目提供了 OpenAI API 服务、Web UI 示例等部署方式,还包含了视觉处理工具,有助于开发者快速集成和使用,提升工作效率。

HunyuanVideo

HunyuanVideo

HunyuanVideo 是一个可基于文本生成高质量图像和视频的项目。

HunyuanVideo 是一个专注于文本到图像及视频生成的项目。它具备强大的视频生成能力,支持多种分辨率和视频长度选择,能根据用户输入的文本生成逼真的图像和视频。使用先进的技术架构和算法,可灵活调整生成参数,满足不同场景的需求,是文本生成图像视频领域的优质工具。

WebUI for Browser Use

WebUI for Browser Use

一个基于 Gradio 构建的 WebUI,支持与浏览器智能体进行便捷交互。

WebUI for Browser Use 是一个强大的项目,它集成了多种大型语言模型,支持自定义浏览器使用,具备持久化浏览器会话等功能。用户可以通过简洁友好的界面轻松控制浏览器智能体完成各类任务,无论是数据提取、网页导航还是表单填写等操作都能高效实现,有利于提高工作效率和获取信息的便捷性。该项目适合开发者、研究人员以及需要自动化浏览器操作的人群使用,在 SEO 优化方面,其关键词涵盖浏览器使用、WebUI、大型语言模型集成等,有助于提高网页在搜索引擎中的曝光度。

xiaozhi-esp32

xiaozhi-esp32

基于 ESP32 的小智 AI 开发项目,支持多种网络连接与协议,实现语音交互等功能。

xiaozhi-esp32 是一个极具创新性的基于 ESP32 的开发项目,专注于人工智能语音交互领域。项目涵盖了丰富的功能,如网络连接、OTA 升级、设备激活等,同时支持多种语言。无论是开发爱好者还是专业开发者,都能借助该项目快速搭建起高效的 AI 语音交互系统,为智能设备开发提供强大助力。

olmocr

olmocr

一个用于 OCR 的项目,支持多种模型和服务器进行 PDF 到 Markdown 的转换,并提供测试和报告功能。

olmocr 是一个专注于光学字符识别(OCR)的 Python 项目,由 Allen Institute for Artificial Intelligence 开发。它支持多种模型和服务器,如 vllm、sglang、OpenAI 等,可将 PDF 文件的页面转换为 Markdown 格式。项目还提供了测试框架和 HTML 报告生成功能,方便用户对 OCR 结果进行评估和分析。适用于科研、文档处理等领域,有助于提高工作效率和准确性。

飞书多维表格

飞书多维表格

飞书多维表格 ×DeepSeek R1 满血版

飞书多维表格联合 DeepSeek R1 模型,提供 AI 自动化解决方案,支持批量写作、数据分析、跨模态处理等功能,适用于电商、短视频、影视创作等场景,提升企业生产力与创作效率。关键词:飞书多维表格、DeepSeek R1、AI 自动化、批量处理、企业协同工具。

下拉加载更多