SpecScore 🚀

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.

Features

• 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

Quick Start

Installation

# Install globally via npm
npm install -g spec-score

# Or use with npx (no installation required)
npx spec-score validate ./openapi.yaml

Basic Usage

# 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.yaml

Commands

validate

Validates an OpenAPI specification for structural correctness and compliance.

spec-score validate <file|url>

Examples:

spec-score validate ./api/openapi.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

report

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

Scoring Criteria

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 |

Grade Scale

• 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

Development

Prerequisites

• Bun >= 1.0.0
• Node.js >= 20 (for compatibility)

Setup

# 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

Support

• Found a bug? Open an issue
• Like this project? Sponsor on GitHub
• Need help? Email: [email protected]

Made with ❤️ by Dhairya Majmudar