docs: Add Comprehensive OpenAPI/Swagger Documentation

[nik-kale]

Summary

This PR adds complete OpenAPI 3.0 documentation with interactive Swagger UI for all API endpoints. Developers can now explore, test, and integrate with the API using industry-standard documentation.

Changes

• Created Swagger configuration (config/swagger.ts):
  • OpenAPI 3.0 spec
  • Complete schema definitions (Mission, MissionStep, etc.)
  • Authentication schemes documented
  • Server configurations
• Added JSDoc annotations to all endpoints:
  • POST /api/missions
  • GET /api/missions
  • GET /api/missions/:id
  • GET /api/missions/:id/stream
  • GET /health
• Set up Swagger UI:
  • Accessible at /api/docs
  • Interactive API playground
  • Try-it-out functionality
• OpenAPI JSON export:
  • Available at /api/docs/openapi.json
  • For SDK generation and tooling

Type of Change

• Documentation update
• New feature (Swagger UI)
• Bug fix
• Breaking change
• Performance improvement

API Documentation Features

• ✅ Interactive Swagger UI at /api/docs
• ✅ Complete schema definitions for all data models
• ✅ Request/response examples
• ✅ Authentication documentation (JWT Bearer)
• ✅ Error response schemas
• ✅ Tags and grouping (Missions, Health)
• ✅ OpenAPI 3.0 JSON export

Access Points

Endpoint	Description
/api/docs	Interactive Swagger UI
/api/docs/openapi.json	OpenAPI 3.0 spec (JSON)

Swagger UI Features

• 📚 Complete API reference
• 🧪 Try-it-out testing
• 🔐 Authentication support
• 📝 Request/response examples
• 🏷️ Tagged endpoints
• 📊 Schema browser

Testing

• ✅ No linting errors
• ✅ Swagger UI accessible at /api/docs
• ✅ OpenAPI JSON exports correctly
• ✅ All endpoints documented
• ✅ Schemas properly defined
• ✅ Authentication scheme documented

Screenshots

Swagger UI provides:

• Endpoint explorer
• Request builder
• Response viewer
• Schema documentation
• Authentication UI

SDK Generation

The OpenAPI spec enables automatic client generation:

# Generate TypeScript client
npx openapi-generator-cli generate \
  -i http://localhost:3001/api/docs/openapi.json \
  -g typescript-axios \
  -o ./sdk/typescript

# Generate Python client
npx openapi-generator-cli generate \
  -i http://localhost:3001/api/docs/openapi.json \
  -g python \
  -o ./sdk/python

Checklist

• Code follows project style guidelines
• Self-review completed
• All endpoints documented
• No new warnings introduced
• Swagger UI functional
• OpenAPI 3.0 compliant

Related Issues

Addresses Feature #7 from FEATURE_OPPORTUNITIES.md - Priority Score: 2.0

Notes

• Swagger dependencies already in package.json
• Documentation auto-updates with code changes
• Compatible with Postman, Insomnia, and other API tools

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[nik-kale]

Closing PR - OpenAPI configuration created but Swagger UI integration reverted by user. Config file available in git history.