feat: add OpenAPI spec validation on load with error recovery

[ayomidearegbeshola29-dev]

Summary

This PR adds runtime OpenAPI specification validation to the API reference page. Invalid specs now show clear, actionable error messages instead of Redoc failing silently or showing cryptic errors.

Problem

When an invalid OpenAPI spec is placed in static/openapi.yaml, Redoc either fails silently or displays cryptic error messages that don't help developers identify or fix the issue.

Solution

Added a three-stage validation pipeline that runs on page load:

1. Fetch the YAML spec from the server
2. Parse YAML syntax and catch structural errors with line numbers
3. Validate against the OpenAPI 3.0 schema using @readme/openapi-parser

If validation fails, the user sees a structured error display with:

• Error message explaining what went wrong
• Line number pointing to the location in the spec
• Fix suggestion describing how to resolve the issue
• Retry button to re-fetch and re-validate after fixes

Changes

New Files

File	Purpose
src/utils/validateSpec.ts	YAML parsing + OpenAPI 3.0 validation with error mapping
src/components/SpecErrorDisplay.tsx	Error UI component with suggestions and retry
src/types/modules.d.ts	TypeScript declarations for js-yaml and @readme/openapi-parser

Modified Files

File	Change
src/components/ApiReference.tsx	Replaced direct Redoc render with fetch → validate → render pipeline; added loading/error/invalid states
src/css/custom.css	Added @keyframes spin for loading spinner
package.json	Added js-yaml and @readme/openapi-parser dependencies

Acceptance Criteria

• Validation errors shown to user
• Error message explains issue
• Suggests how to fix
• Points to line in spec
• Validation runs on load

Error Handling Coverage

Scenario	Behavior
Spec file missing (404)	Fetch error with hint to copy spec into static/
Invalid YAML syntax	YAML parse error with line number and fix suggestion
Missing required OpenAPI fields	Schema validation error with field name and example
Invalid property values	Validation error with allowed values and spec reference
Network failure	Error display with retry button

Testing

• Verified with valid spec — renders Redoc normally
• Verified with missing info.title — shows error with line number and suggestion
• Verified with missing info.version — shows error with line number and suggestion
• Verified with invalid YAML syntax — shows YAML parse error with line reference
• Verified with missing spec file — shows fetch error with recovery hint
• Loading spinner displays during validation

Dependencies Added

• js-yaml — YAML parser for browser-side spec parsing
• @readme/openapi-parser — OpenAPI 3.0 schema validation

Closes #221

[drips-wave]

@ayomidearegbeshola29-dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits