This GitHub repository demonstrates how Spectral linting can help align your API specifications with OpenAPI V3 best practices whilst enhancing security through adherence to OWASP rules.
Tip
I’ve also written a more detailed blog post about spectral and how it works in practice, which you can read here.
This repository includes example API specifications in both good and bad forms (.yml and .json formats) to demonstrate how Spectral linting works in practice.
By incorporating Spectral linting into your development workflow, you can:
- 🛡️ Shift-left security - Catch API vulnerabilities before they reach production
- ⚖️ Enforce governance - Ensure all APIs follow your organisation's standards and adhere to OpenAPI specification
- ✨ Maintain consistency - Apply best practices across all your API specifications
Whether you're currently using API linting tools or not, this repository showcases how powerful Spectral can be as part of your CI process, providing immediate benefits for both your API and DevOps teams through automated validation that keeps your API specifications secure, consistent, and high quality.
This demo includes a GitHub Action that runs Spectral linting on every pull request. You can test it by forking the repository and making a change (e.g., updating a description and checking the action output).
├── .github/
│ └── workflows/
│ └── spectral.yml # GitHub Actions workflow for PR checks
├── .spectral.yml # Spectral config (OAS + OWASP rules + Custom)
├── apis/
│ ├── good-example/
│ │ ├── openapi.yml # ✅ Secure API (YAML format)
│ │ └── openapi.json # ✅ Secure API (JSON format)
│ └── bad-example/
│ ├── openapi.yml # ❌ Insecure API (YAML format)
│ └── openapi.json # ❌ Insecure API (JSON format)
Check out the official docs.
Here's how to get up and running with Spectral linting:
-
Install Spectral via CLI or VS Code Extension:
Option 1: CLI Installation
npm install -g @stoplight/spectral-cli
Option 2: VS Code Extension Install the Spectral VS Code Extension for real-time linting on type or save.
Note
You will need to add the yml file extension in the extension settings.
-
Test it out - Run these commands to see Spectral in action:
# Test the secure API (should pass) spectral lint apis/good-example/openapi.yml # Test the secure API in JSON format spectral lint apis/good-example/openapi.json # Test the insecure API (you'll see plenty of violations) spectral lint apis/bad-example/openapi.yml spectral lint apis/bad-example/openapi.json
-
Automated validation - GitHub Action runs Spectral automatically on every pull request.
This setup uses a powerful combination:
- OpenAPI v3 recommended rules (
spectral:oas, recommended) - Catches common API design issues using OpenAPI V3 recommended ruleset - OWASP API Security rules - Validates against real security vulnerabilities
- Custom Rules - Included is an example custom rule which you can create to adhere to your specific organistions styling and standards
Check out spectral-rulesets and spectral-owasp-ruleset for the complete rule breakdowns. You can also create your own custom rules.
Both examples ship in YAML and JSON formats. These are demo API specifications to showcase validation.
✅ Good Example (apis/good-example/):
- 0 errors, 0 warnings - This is what success looks like
- 🔒 OWASP API Security Top 10 compliance baked in
- 🎯 OpenAPI v3 best practices throughout
- 📝 OAuth2 with PKCE, proper error handling, rate limiting, etc
❌ Bad Example (apis/bad-example/):
- 33 errors, 116 warnings - Shows spectral linting catching a bad example API specification
- 🚫 Security vulnerabilities highlighted from OWASP rulset
- 📚 Educational goldmine help hightlight bad practices in an API spec
⚠️ HTTP servers, credentials in URLs, missing security - all the facepalm security issues to show spectral working to help keep your specifications secure before it hitsmain