Spoonacular API Rules
Spectral linting rules defining API design standards and conventions for Spoonacular.
20 Rules
error 6
warn 11
info 3
Rule Categories
info
openapi
operation
parameter
paths
response
security
servers
tag
Rules
warn
info-title-prefix
API title should reference spoonacular.
$.info
warn
info-description-required
Info object must have a non-empty description.
$.info
error
info-version-required
Info object must declare a version.
$.info
error
openapi-version-3
Spec must be OpenAPI 3.x.
$
error
servers-defined
A servers array must be defined.
$
error
servers-https
Server URLs must use HTTPS.
$.servers[*]
warn
paths-no-trailing-slash
Paths should not end with a trailing slash.
$.paths[*]~
info
paths-camel-case
Path segments use camelCase (Spoonacular convention, e.g. /recipes/complexSearch).
$.paths[*]~
warn
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,delete,patch]
warn
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,delete,patch]
error
operation-operationid-required
Every operation must have an operationId.
$.paths[*][get,post,put,delete,patch]
warn
operation-operationid-camel-case
operationId should be camelCase (e.g. searchRecipes, getRecipeInformation).
$.paths[*][get,post,put,delete,patch].operationId
warn
operation-tags-required
Every operation must be tagged.
$.paths[*][get,post,put,delete,patch]
warn
tag-title-case
Tag names must be Title Case (e.g. Recipes, Meal Planning, Menu Items).
$.paths[*][get,post,put,delete,patch].tags[*]
info
parameter-description-required
Parameters should have a description.
$.paths[*][get,post,put,delete,patch].parameters[*]
warn
parameter-schema-typed
Parameters must define a typed schema.
$.paths[*][get,post,put,delete,patch].parameters[*].schema
warn
response-success-defined
Operations must define a 200 (or 2xx) success response.
$.paths[*][get,post,put,delete,patch].responses
warn
security-global-defined
A global security requirement must be declared.
$
error
security-apikey-header
The API key security scheme must be an apiKey delivered in the x-api-key header.
$.components.securitySchemes.apiKeyScheme
info
operation-examples-encouraged
Operations are encouraged to provide response examples for mocking.
$.paths[*][get,post,put,delete,patch].responses[*].content[*]
Spectral Ruleset
# Spectral ruleset for the Spoonacular Recipe and Food API
# Generated by the API Evangelist pipeline from the official Spoonacular OpenAPI 3 spec
# (ddsky/spoonacular-api-clients). Enforces the conventions observed across the spec:
# - camelCase paths and operationIds
# - Title Case tags
# - API key auth via the x-api-key header
# - offset / number pagination
extends: [[spectral:oas, off]]
rules:
# ---------------------------------------------------------------
# INFO / METADATA
# ---------------------------------------------------------------
info-title-prefix:
description: API title should reference spoonacular.
severity: warn
given: $.info
then:
field: title
function: pattern
functionOptions:
match: "(?i)spoonacular"
info-description-required:
description: Info object must have a non-empty description.
severity: warn
given: $.info
then:
field: description
function: truthy
info-version-required:
description: Info object must declare a version.
severity: error
given: $.info
then:
field: version
function: truthy
# ---------------------------------------------------------------
# OPENAPI VERSION
# ---------------------------------------------------------------
openapi-version-3:
description: Spec must be OpenAPI 3.x.
severity: error
given: $
then:
field: openapi
function: pattern
functionOptions:
match: "^3\\."
# ---------------------------------------------------------------
# SERVERS
# ---------------------------------------------------------------
servers-defined:
description: A servers array must be defined.
severity: error
given: $
then:
field: servers
function: truthy
servers-https:
description: Server URLs must use HTTPS.
severity: error
given: $.servers[*]
then:
field: url
function: pattern
functionOptions:
match: "^https://"
# ---------------------------------------------------------------
# PATHS — NAMING CONVENTIONS
# ---------------------------------------------------------------
paths-no-trailing-slash:
description: Paths should not end with a trailing slash.
severity: warn
given: $.paths[*]~
then:
function: pattern
functionOptions:
notMatch: ".+/$"
paths-camel-case:
description: Path segments use camelCase (Spoonacular convention, e.g. /recipes/complexSearch).
severity: info
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^(/[a-zA-Z0-9{}\\-]+)+$"
# ---------------------------------------------------------------
# OPERATIONS
# ---------------------------------------------------------------
operation-summary-required:
description: Every operation must have a summary.
severity: warn
given: $.paths[*][get,post,put,delete,patch]
then:
field: summary
function: truthy
operation-description-required:
description: Every operation must have a description.
severity: warn
given: $.paths[*][get,post,put,delete,patch]
then:
field: description
function: truthy
operation-operationid-required:
description: Every operation must have an operationId.
severity: error
given: $.paths[*][get,post,put,delete,patch]
then:
field: operationId
function: truthy
operation-operationid-camel-case:
description: operationId should be camelCase (e.g. searchRecipes, getRecipeInformation).
severity: warn
given: $.paths[*][get,post,put,delete,patch].operationId
then:
function: pattern
functionOptions:
match: "^[a-z][a-zA-Z0-9]*$"
operation-tags-required:
description: Every operation must be tagged.
severity: warn
given: $.paths[*][get,post,put,delete,patch]
then:
field: tags
function: truthy
# ---------------------------------------------------------------
# TAGS
# ---------------------------------------------------------------
tag-title-case:
description: Tag names must be Title Case (e.g. Recipes, Meal Planning, Menu Items).
severity: warn
given: $.paths[*][get,post,put,delete,patch].tags[*]
then:
function: pattern
functionOptions:
match: "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$"
# ---------------------------------------------------------------
# PARAMETERS
# ---------------------------------------------------------------
parameter-description-required:
description: Parameters should have a description.
severity: info
given: $.paths[*][get,post,put,delete,patch].parameters[*]
then:
field: description
function: truthy
parameter-schema-typed:
description: Parameters must define a typed schema.
severity: warn
given: $.paths[*][get,post,put,delete,patch].parameters[*].schema
then:
field: type
function: truthy
# ---------------------------------------------------------------
# RESPONSES
# ---------------------------------------------------------------
response-success-defined:
description: Operations must define a 200 (or 2xx) success response.
severity: warn
given: $.paths[*][get,post,put,delete,patch].responses
then:
field: "200"
function: truthy
# ---------------------------------------------------------------
# SECURITY
# ---------------------------------------------------------------
security-global-defined:
description: A global security requirement must be declared.
severity: warn
given: $
then:
field: security
function: truthy
security-apikey-header:
description: The API key security scheme must be an apiKey delivered in the x-api-key header.
severity: error
given: $.components.securitySchemes.apiKeyScheme
then:
- field: type
function: pattern
functionOptions:
match: "^apiKey$"
- field: in
function: pattern
functionOptions:
match: "^header$"
- field: name
function: pattern
functionOptions:
match: "^x-api-key$"
# ---------------------------------------------------------------
# GENERAL QUALITY
# ---------------------------------------------------------------
operation-examples-encouraged:
description: Operations are encouraged to provide response examples for mocking.
severity: info
given: $.paths[*][get,post,put,delete,patch].responses[*].content[*]
then:
function: defined
field: examples