spectral
Use when configuring Spectral for API linting, creating custom rulesets, and validating OpenAPI or AsyncAPI specifications
When & Why to Use This Skill
This Claude skill empowers developers to automate API governance and quality assurance using Spectral. It facilitates the creation of custom rulesets and the rigorous validation of OpenAPI and AsyncAPI specifications, ensuring that API designs are consistent, secure, and compliant with industry standards before implementation.
Use Cases
- Automated API Linting: Instantly validate OpenAPI or AsyncAPI definitions against standard rulesets to catch design errors and documentation gaps early in the development cycle.
- Custom Style Guide Enforcement: Create and apply organization-specific rulesets to ensure all microservices follow consistent naming conventions, security headers, and response structures.
- Ruleset Development & Debugging: Assist in writing complex JSONPath expressions and custom functions for Spectral to target specific parts of an API specification for validation.
- CI/CD Pipeline Integration: Provide guidance on configuring Spectral CLI within automated workflows to prevent non-compliant API contracts from being merged or deployed.
| name | spectral |
|---|---|
| description | Use when configuring Spectral for API linting, creating custom rulesets, and validating OpenAPI or AsyncAPI specifications |
Spectral API Linting
Quick Start
# .spectral.yaml
extends: spectral:oas
rules:
operation-operationId: error
info-contact: warn
oas3-api-servers: off
Core Concepts
- Rulesets: Collections of rules; extend built-in (
spectral:oas,spectral:asyncapi) - Severity:
error,warn,info,hint, oroffto disable - Given: JSONPath expression targeting what to validate
- Then: Functions and conditions to check
Custom Rules
rules:
must-have-description:
description: All operations must have descriptions
given: $.paths[*][get,post,put,patch,delete]
severity: error
then:
field: description
function: truthy
path-must-be-kebab-case:
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^(/[a-z0-9-]+)+$"
Built-in Functions
truthy/falsy- Value exists / is emptypattern- Regex matchinglength- String/array length constraintsenumeration- Value in allowed listschema- Validate against JSON Schemaalphabetical- Keys in orderundefined- Property must not exist
CLI Usage
spectral lint openapi.yaml
spectral lint openapi.yaml --ruleset .spectral.yaml
spectral lint openapi.yaml -f json # JSON output
Reference Files
- references/functions.md - All built-in functions
- references/custom-functions.md - Writing custom functions
- references/jsonpath.md - JSONPath expressions