光谱 JSON:API 规则集

使用此 Spectral ruleset 自动检查 OpenAPI 描述是否符合 JSON:API v1.1 , 这样 API 团队就可以及早在编辑器, CI 中捕捉出问题并拉出请求.

QQ 快速启动

npm install --save-dev spectral-jsonapi @stoplight/spectral-cli

创建本地规则集文件 :

# .spectral.yaml
extends:
  - spectral:oas
  - "@apisyouwonthate/spectral-jsonapi"

显示您的 OpenAPI 描述 :

spectral lint api/openapi.yaml

使用量

用作 npm 软件包

当工程已经安装 npm 的依赖时使用此功能 .

# .spectral.yaml
extends:
  - spectral:oas
  - "@apisyouwonthate/spectral-jsonapi"

从 GitHub 直接使用遗留的 YAML

如果您想要不安装软件包而消耗生成的 YAML 规则集, 请使用 :

extends:
  - "https://raw.githubusercontent.com/apisyouwonthate/spectral-jsonapi/refs/heads/main/.spectral.yml"

一旦设置了规则,您就可以在相同的目录中运行 Spectral .spectral.yml 规则,它将包含 JSON: API 规则在它的检查中

spectral lint api/openapi.yaml

这不包括: spectral:oas 规则,所以得到这些 加到 extend 列表 :

extends:
  - "https://raw.githubusercontent.com/apisyouwonthate/spectral-jsonapi/refs/heads/main/.spectral.yml"
  - spectral:oas

规则外出

资源对象- id- 需要

仅在一个响应计划故意不是标准JSON:API资源对象(例如,没有稳定ID的ephemeral计算资源)时才使用此选择退出.

设定 x-jsonapi-virtual-resource: true 用于跳过 resource-object-id-required 警告 警告他们.

components:
  schemas:
    AvailableSlotResource:
      type: object
      x-jsonapi-virtual-resource: true
      required:
        - type
        - attributes
      properties:
        type:
          type: string
          enum:
            - availableSlot
        attributes:
          $ref: "#/components/schemas/AvailableSlotAttributes"

捐款

关于测试方法和贡献者工作流程,见 捐款额。 。 。 .

谢谢

• 杰夫·马尔克斯
• 阿里·法扎尔
• 阿纳尼亚·波德达尔
• 安东尼·麦克阿利斯特

许可证

麻省理工学院. 见 自由主义。 。 。 .

提案国

如果你愿意感谢这个风格指南,考虑支持 保护地球由APIs You Won't Hate联合创办的慈善机构 菲尔·斯德克森 专注于自然气候解决方案 菲尔花大部分时间种树 和再湿的沼泽现在, 特别是在 沃利自然保护区因此,这是一个伟大的方法 支持他的工作和地球 同时.