Spiceworks · API Governance Rules

Spiceworks API Rules

Spectral linting rules defining API design standards and conventions for Spiceworks.

8 Rules error 2 warn 6

View Rules File View on GitHub

Rule Categories

spiceworks

Rules

warn

spiceworks-operation-summary-title-case

All operation summaries must use Title Case

$.paths[*][*].summary

warn

spiceworks-tags-title-case

All tags must use Title Case

$.tags[*].name

error

spiceworks-operation-tags

All operations must have at least one tag

$.paths[*][get,post,put,patch,delete]

error

spiceworks-operation-id

All operations must have an operationId

$.paths[*][get,post,put,patch,delete]

warn

spiceworks-operation-description

All operations must have a description

$.paths[*][get,post,put,patch,delete]

warn

spiceworks-path-kebab-case

Path segments must use kebab-case

$.paths[*]~

warn

spiceworks-response-200-schema

GET operations must define a 200 response schema

$.paths[*].get.responses.200.content

warn

spiceworks-security-defined

All operations should have security defined

$.paths[*][get,post,put,patch,delete]

Spectral Ruleset

extends: spectral:oas
rules:
  spiceworks-operation-summary-title-case:
    description: All operation summaries must use Title Case
    message: Operation summary "{{value}}" should be in Title Case
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*([ ][A-Z][a-zA-Z0-9]*)*$"

  spiceworks-tags-title-case:
    description: All tags must use Title Case
    message: Tag "{{value}}" should be in Title Case
    severity: warn
    given: "$.tags[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*([ ][A-Z][a-zA-Z0-9]*)*$"

  spiceworks-operation-tags:
    description: All operations must have at least one tag
    message: Operation must have at least one tag
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  spiceworks-operation-id:
    description: All operations must have an operationId
    message: Operation must have an operationId
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  spiceworks-operation-description:
    description: All operations must have a description
    message: Operation should have a description
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  spiceworks-path-kebab-case:
    description: Path segments must use kebab-case
    message: Path segment "{{value}}" should use kebab-case (lowercase with hyphens)
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{][a-z0-9_{}/-]*)*$"

  spiceworks-response-200-schema:
    description: GET operations must define a 200 response schema
    message: GET operation should define a 200 response with a schema
    severity: warn
    given: "$.paths[*].get.responses.200.content"
    then:
      function: truthy

  spiceworks-security-defined:
    description: All operations should have security defined
    message: Operation should define security requirements
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: security
      function: defined