stoplight/spectral

Spectral

Spectral 是一个灵活的 JSON/YAML linter，可帮助您确保 API 描述文档的质量和一致性。它提供了自定义规则集功能，以及对 OpenAPI、AsyncAPI 和 Arazzo 等 API 规范的内置支持。

主要特性

• 自定义规则集：创建自定义规则来检查 JSON 或 YAML 对象
• 即用型规则集：验证和检查 OpenAPI v2 & v3.x、AsyncAPI 和 Arazzo v1 文档
• API 风格指南：使用规则集实现自动化 API 风格指南，提高所有 API 的一致性
• 内置函数：提供一组内置函数来帮助创建自定义规则，包括模式检查、参数检查、字母顺序排序、字符数限制、对象中指定键的存在性检查等
• 自定义函数：为高级用例创建自定义函数

安装

安装 Spectral 的最简单方法是使用 npm：

bash
npm install -g @stoplight/spectral-cli

或 yarn：

bash
yarn global add @stoplight/spectral-cli

Docker 部署方案

bash
# 使用 Docker 运行 Spectral
# 创建规则集文件
docker run --rm -v $(pwd):/work stoplight/spectral echo 'extends: ["spectral:oas", "spectral:asyncapi", "spectral:arazzo"]' > /work/.spectral.yaml

# 检查 API 文档
docker run --rm -v $(pwd):/work stoplight/spectral lint /work/openapi.yaml

# 使用自定义规则集检查
docker run --rm -v $(pwd):/work stoplight/spectral lint /work/openapi.yaml --ruleset /work/custom-ruleset.yaml

使用方法

1. 创建本地规则集

Spectral 需要规则集来检查文件。规则集是 JSON、YAML 或 JavaScript/TypeScript 文件（通常命名为 .spectral.yaml），包含一组用于检查其他 JSON 或 YAML 文件的规则。

创建基础规则集：

bash
echo 'extends: ["spectral:oas", "spectral:asyncapi", "spectral:arazzo"]' > .spectral.yaml

2. 执行检查

使用当前目录的规则集检查文件：

bash
spectral lint myapifile.yaml

使用自定义规则集检查：

bash
spectral lint myapifile.yaml --ruleset myruleset.yaml

文档资源

• 官方文档 - Spectral 的完整文档
• 入门指南 - 了解 Spectral 的基础知识
• 规则集 - 了解规则集结构

支持

• https://github.com/stoplightio/spectral/discussions - 讨论和问题解答
• Stoplight 社区论坛 - 分享规则集和使用经验
• https://github.com/stoplightio/spectral/issues - 报告错误或功能请求

实际应用规则集

• OWASP Top 10 - 执行 OWASP 安全指南的规则集
• URL 风格指南 - 帮助创建一致端点的规则集
• https://github.com/adidas/api-guidelines/blob/master/.spectral.yml - Adidas API 风格指南规则集
• https://github.com/Azure/azure-api-style-guide/blob/main/spectral.yaml - Azure 服务 OpenAPI 定义规则集

集成

• https://github.com/stoplightio/spectral-action - 检查仓库中的文档
• JetBrains 插件 - 编辑器中的实时检查
• VS Code 扩展 - VS Code 中的 Spectral 功能

许可证

Spectral 基于 Apache License 2.0 许可，100% 免费和开源。