A lightweight, fast CLI tool for OpenAPI specification validation and quality scoring. SpecScore helps you ensure your API documentation follows best practices and industry standards.
- Comprehensive Validation - Validates OpenAPI 3.x specifications using swagger-parser
- Quality Scoring - Evaluates your API spec across 7 key criteria with detailed feedback
- Multiple Output Formats - Console, Markdown, and HTML reports
- URL & File Support - Works with local files and remote URLs
- Fast & Lightweight - Built with Bun for optimal performance
- Actionable Insights - Get specific suggestions for improvement
# Install globally via npm
npm install -g spec-score
# Or use with npx (no installation required)
npx spec-score validate ./openapi.yaml# Validate an OpenAPI specification
spec-score validate ./openapi.yaml
# Validate from URL
spec-score validate https://api.example.com/openapi.json
# Generate a detailed scoring report
spec-score report ./openapi.yamlValidates an OpenAPI specification for structural correctness and compliance.
spec-score validate <file|url>Examples:
spec-score validate spec.yaml
spec-score validate https://petstore3.swagger.io/api/v3/openapi.json
Output includes:
- Document parsing and validation status
- API information (title, version, description)
- Statistics (paths, operations, schemas, parameters)
- Warnings and suggestions
Generates a comprehensive quality report with scoring across multiple criteria.
spec-score report <file|url> [options]Options:
-f, --format <format>- Output format:console,markdown,html(default: console)-o, --output <file>- Output file path (required for markdown/html formats)
Examples:
# Console report (default)
spec-score report ./openapi.yaml
# Markdown report
spec-score report ./openapi.yaml -f markdown -o api-report.md
# HTML report
spec-score report ./openapi.yaml -f html -o api-report.html
SpecScore evaluates your OpenAPI specification across 7 key areas:
| Criteria | Max Points | Description |
|---|---|---|
| Schema & Types | 20 | Proper data types, schema definitions, and type safety |
| Descriptions & Documentation | 20 | Comprehensive descriptions for operations, parameters, and responses |
| Paths & Operations | 15 | RESTful naming conventions and CRUD patterns |
| Response Codes | 15 | Appropriate HTTP status codes for different scenarios |
| Examples & Samples | 10 | Request/response examples for better developer experience |
| Security | 10 | Security schemes and authentication methods |
| Best Practices | 10 | Versioning, servers, tags, and component reuse |
- A (80-100): Excellent - Follows industry best practices
- B (70-79): Good - Well-structured with minor improvements needed
- C (60-69): Decent - Several areas for improvement
- D (50-59): Needs work - Significant improvements required
- F (0-49): Poor - Major improvements needed across multiple areas
- Bun >= 1.0.0
- Node.js >= 20 (for compatibility)
# Clone the repository
git clone https://github.com/DhairyaMajmudar/SpecScore.git
cd SpecScore
# Install dependencies
bun install
# Build the project
bun run build
# Start CLI locally
bun run index.ts [command] [flags]
# Run tests
bun test- Found a bug? Open an issue
- Like this project? Sponsor on GitHub
- Need help? Email: [email protected]
Made with ❤️ by Dhairya Majmudar