Tools: Spec Guard: AI-Powered API Spec Compliance Tool

Description ## GitHub Repo ## Quick Start Spec Guard: AI-Powered API Spec Compliance Tool Spec Guard ensures your FastAPI implementation matches your OpenAPI specification using GitHub Copilot CLI to automatically fix drift issues. Every API team faces the same problem: you write a beautiful OpenAPI spec, but over time your implementation drifts. Missing validations, wrong status codes, undocumented endpoints—these bugs slip into production. Spec Guard solves this by: Key Innovation: Spec Guard doesn't just call Copilot once—it orchestrates multi-step fix workflows with validation loops. If a fix fails, it retries with error context, demonstrating sophisticated AI orchestration. Tech Stack: Python, FastAPI, OpenAPI 3.0, AST parsing, GitHub Copilot CLI, Rich (terminal UI). [![Spec Guard Demo]https://github.com/Kitan-Dara06/spec-guard/issues/1#issue-3941223574 🔗 ](https://github.com/Kitan-Dara06/spec-guard) Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse COMMAND_BLOCK: bash # Install pip install -e . # Analyze API drift spec-guard analyze --spec api.yaml --code app.py # Auto-fix with Copilot CLI spec-guard fix --spec api.yaml --code app.py Journey: How I Used GitHub Copilot CLI The Challenge I wanted to build a tool that helps developers maintain API consistency—a real problem I've faced on every team. But implementing drift detection across 10+ validation types (enums, patterns, ranges, error handling, status codes) seemed overwhelming. How Copilot CLI Transformed Development 1. Architectural Decisions (Week 1) I was stuck deciding between using regex or AST parsing for code analysis. I asked Copilot CLI: gh copilot suggest "Should I use regex or AST to parse FastAPI decorators?" Copilot explained AST parsing would be more robust and even suggested using ast.AsyncFunctionDef for async functions—something I completely missed! This saved me from a critical bug where the scanner would have found 0 routes. 2. Debugging the "NoneType is not iterable" Error (Week 2) When integrating components, I hit a mysterious error. The stack trace was unclear. I ran: gh copilot explain "Getting 'NoneType' object is not iterable when analyzing spec validations" Copilot identified that my _extract_validations() function was returning None when there was no request body—the return statement was indented inside an if-block! Fixed in 30 seconds. 3. Building the Copilot Orchestrator (Week 2-3) The irony wasn't lost on me: I was building a tool that uses Copilot CLI, and I used Copilot CLI to build it! For the retry logic, I asked: gh copilot suggest "How to implement retry logic with error context in Python async" Copilot generated a complete retry loop with exponential backoff that I adapted for the validation workflow. The orchestrator became the centerpiece of the project. 4. The AsyncFunctionDef Discovery (Week 3) When the scanner found 0 routes despite working code, I was stumped. I asked: gh copilot suggest "Why does ast.walk find 0 FunctionDef nodes in FastAPI code with async def?" Copilot immediately explained: "FastAPI uses async def, which creates AsyncFunctionDef nodes, not FunctionDef." Boom. Changed one line, went from 0 → 5 routes detected. The Meta Moment The most profound moment: I was building a tool that uses GitHub Copilot CLI to fix code drift, while using GitHub Copilot CLI to fix my own code drift. This recursive, meta usage of AI tools showed me the future of development—AI systems that improve AI systems. Spec Guard proves that GitHub Copilot CLI isn't just a code generator—it's a thought partner for building complex, production-ready developer tools Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: bash # Install pip install -e . # Analyze API drift spec-guard analyze --spec api.yaml --code app.py # Auto-fix with Copilot CLI spec-guard fix --spec api.yaml --code app.py Journey: How I Used GitHub Copilot CLI The Challenge I wanted to build a tool that helps developers maintain API consistency—a real problem I've faced on every team. But implementing drift detection across 10+ validation types (enums, patterns, ranges, error handling, status codes) seemed overwhelming. How Copilot CLI Transformed Development 1. Architectural Decisions (Week 1) I was stuck deciding between using regex or AST parsing for code analysis. I asked Copilot CLI: gh copilot suggest "Should I use regex or AST to parse FastAPI decorators?" Copilot explained AST parsing would be more robust and even suggested using ast.AsyncFunctionDef for async functions—something I completely missed! This saved me from a critical bug where the scanner would have found 0 routes. 2. Debugging the "NoneType is not iterable" Error (Week 2) When integrating components, I hit a mysterious error. The stack trace was unclear. I ran: gh copilot explain "Getting 'NoneType' object is not iterable when analyzing spec validations" Copilot identified that my _extract_validations() function was returning None when there was no request body—the return statement was indented inside an if-block! Fixed in 30 seconds. 3. Building the Copilot Orchestrator (Week 2-3) The irony wasn't lost on me: I was building a tool that uses Copilot CLI, and I used Copilot CLI to build it! For the retry logic, I asked: gh copilot suggest "How to implement retry logic with error context in Python async" Copilot generated a complete retry loop with exponential backoff that I adapted for the validation workflow. The orchestrator became the centerpiece of the project. 4. The AsyncFunctionDef Discovery (Week 3) When the scanner found 0 routes despite working code, I was stumped. I asked: gh copilot suggest "Why does ast.walk find 0 FunctionDef nodes in FastAPI code with async def?" Copilot immediately explained: "FastAPI uses async def, which creates AsyncFunctionDef nodes, not FunctionDef." Boom. Changed one line, went from 0 → 5 routes detected. The Meta Moment The most profound moment: I was building a tool that uses GitHub Copilot CLI to fix code drift, while using GitHub Copilot CLI to fix my own code drift. This recursive, meta usage of AI tools showed me the future of development—AI systems that improve AI systems. Spec Guard proves that GitHub Copilot CLI isn't just a code generator—it's a thought partner for building complex, production-ready developer tools COMMAND_BLOCK: bash # Install pip install -e . # Analyze API drift spec-guard analyze --spec api.yaml --code app.py # Auto-fix with Copilot CLI spec-guard fix --spec api.yaml --code app.py Journey: How I Used GitHub Copilot CLI The Challenge I wanted to build a tool that helps developers maintain API consistency—a real problem I've faced on every team. But implementing drift detection across 10+ validation types (enums, patterns, ranges, error handling, status codes) seemed overwhelming. How Copilot CLI Transformed Development 1. Architectural Decisions (Week 1) I was stuck deciding between using regex or AST parsing for code analysis. I asked Copilot CLI: gh copilot suggest "Should I use regex or AST to parse FastAPI decorators?" Copilot explained AST parsing would be more robust and even suggested using ast.AsyncFunctionDef for async functions—something I completely missed! This saved me from a critical bug where the scanner would have found 0 routes. 2. Debugging the "NoneType is not iterable" Error (Week 2) When integrating components, I hit a mysterious error. The stack trace was unclear. I ran: gh copilot explain "Getting 'NoneType' object is not iterable when analyzing spec validations" Copilot identified that my _extract_validations() function was returning None when there was no request body—the return statement was indented inside an if-block! Fixed in 30 seconds. 3. Building the Copilot Orchestrator (Week 2-3) The irony wasn't lost on me: I was building a tool that uses Copilot CLI, and I used Copilot CLI to build it! For the retry logic, I asked: gh copilot suggest "How to implement retry logic with error context in Python async" Copilot generated a complete retry loop with exponential backoff that I adapted for the validation workflow. The orchestrator became the centerpiece of the project. 4. The AsyncFunctionDef Discovery (Week 3) When the scanner found 0 routes despite working code, I was stumped. I asked: gh copilot suggest "Why does ast.walk find 0 FunctionDef nodes in FastAPI code with async def?" Copilot immediately explained: "FastAPI uses async def, which creates AsyncFunctionDef nodes, not FunctionDef." Boom. Changed one line, went from 0 → 5 routes detected. The Meta Moment The most profound moment: I was building a tool that uses GitHub Copilot CLI to fix code drift, while using GitHub Copilot CLI to fix my own code drift. This recursive, meta usage of AI tools showed me the future of development—AI systems that improve AI systems. Spec Guard proves that GitHub Copilot CLI isn't just a code generator—it's a thought partner for building complex, production-ready developer tools - 📊 Analyzing your OpenAPI spec vs FastAPI code to detect 10+ types of drift. - 🔍 Identifying missing validations, wrong status codes, and undocumented errors. - 🤖 Auto-fixing issues using GitHub Copilot CLI with intelligent retry logic. - ✅ Validating that fixes actually work before applying them. - 📈 Reporting before/after compliance metrics with beautiful terminal output.