Skip to content

README.md

Latest commit

 

History

History
58 lines (42 loc) · 1.68 KB

README.md

File metadata and controls

58 lines (42 loc) · 1.68 KB

API Documentation

Validate OpenAPI Specification

Using Copilot (Recommended)

The easiest way to run comprehensive validation is using GitHub Copilot:

@workspace /validate-openapi

This runs 7 validation checks including:

  • VS Code error detection
  • OpenAPI spec validation (rdme)
  • JSON syntax validation
  • RAW_BODY anti-pattern detection
  • External schema reference verification
  • File metrics and reduction tracking

Manual Validation

OpenAPI Spec Validation (rdme)

cd reference
npx --yes rdme openapi validate rest-api.json

Legacy swagger-cli

cd reference
swagger-cli validate rest-api.json

Complete Validation Script

# Combined validation report
printf "=== VALIDATION REPORT ===\n\n" && \
printf "1. File Size:\n" && wc -l reference/rest-api.json && \
printf "\n2. OpenAPI Spec:\n" && cd reference && npx --yes rdme openapi validate rest-api.json && cd .. && \
printf "\n3. JSON Syntax:\n" && node -e "const fs = require('fs'); try { JSON.parse(fs.readFileSync('reference/rest-api.json', 'utf-8')); console.log('✅ Valid JSON'); } catch(e) { console.log('❌ Invalid:', e.message); }" && \
printf "\n4. External References:\n" && grep -c "\$ref.*components/schemas" reference/rest-api.json && \
printf "\n5. RAW_BODY Check:\n" && (grep -c "RAW_BODY" reference/rest-api.json 2>/dev/null || echo "0 - None found ✅") && \
printf "\n6. Schema Files:\n" && ls reference/components/schemas/*.json | wc -l

Documentation Guidelines

See AGENTS.md for detailed instructions on:

  • Working with OpenAPI and JSON Schema files
  • Validation requirements
  • Schema organization best practices
  • Common issues to avoid