sensible-so · API Governance Rules

sensible-so API Rules

Spectral linting rules defining API design standards and conventions for sensible-so.

12 Rules error 9 warn 3
View Rules File View on GitHub

Rule Categories

info operation path response security servers

Rules

error
info-title-required
Info title must be present
$.info
error
info-description-required
Info description must be present
$.info
warn
info-contact-required
Sensible specs should expose contact info
$.info
error
servers-required
Servers block must be present
$
error
servers-production-url
At least one server must point at https://api.sensible.so/v0
$.servers[*]
error
security-bearer-required
Sensible authenticates with a bearer API key
$.components.securitySchemes
error
operation-operationid-required
Every operation must have an operationId
$.paths[*][get,post,put,patch,delete]
error
operation-summary-required
Every operation must have a summary
$.paths[*][get,post,put,patch,delete]
error
operation-tags-required
Every operation must have tags
$.paths[*][get,post,put,patch,delete]
error
response-description-required
Every response must have a description
$.paths[*][get,post,put,patch,delete].responses[*]
warn
response-429-required
Endpoints under quota must document 429 Too Many Requests
$.paths[*][post,put,patch,delete]
warn
path-snake-case
Sensible paths use snake_case (e.g. /extract_from_url, /document_types).
$.paths

Spectral Ruleset

Raw ↑ 
rules:
  info-title-required:
    description: Info title must be present
    severity: error
    given: $.info
    then: {field: title, function: truthy}
  info-description-required:
    description: Info description must be present
    severity: error
    given: $.info
    then: {field: description, function: truthy}
  info-contact-required:
    description: Sensible specs should expose contact info
    severity: warn
    given: $.info
    then: {field: contact, function: truthy}
  servers-required:
    description: Servers block must be present
    severity: error
    given: $
    then: {field: servers, function: truthy}
  servers-production-url:
    description: At least one server must point at https://api.sensible.so/v0
    severity: error
    given: $.servers[*]
    then: {field: url, function: pattern, functionOptions: {match: '^https://api\\.sensible\\.so/v0'}}
  security-bearer-required:
    description: Sensible authenticates with a bearer API key
    severity: error
    given: $.components.securitySchemes
    then: {field: bearerAuth, function: truthy}
  operation-operationid-required:
    description: Every operation must have an operationId
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then: {field: operationId, function: truthy}
  operation-summary-required:
    description: Every operation must have a summary
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then: {field: summary, function: truthy}
  operation-tags-required:
    description: Every operation must have tags
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then: {field: tags, function: truthy}
  response-description-required:
    description: Every response must have a description
    severity: error
    given: $.paths[*][get,post,put,patch,delete].responses[*]
    then: {field: description, function: truthy}
  response-429-required:
    description: Endpoints under quota must document 429 Too Many Requests
    severity: warn
    given: $.paths[*][post,put,patch,delete]
    then: {field: responses.429, function: truthy}
  path-snake-case:
    description: Sensible paths use snake_case (e.g. /extract_from_url, /document_types).
    severity: warn
    given: $.paths
    then:
      function: pattern
      functionOptions: {match: '^/[a-z0-9_/{}]+$'}