#224 OpenAPI/Swagger: Infrastructure Setup and Library Integration

## Overview Set up OpenAPI 3.0 specification infrastructure for Highway Workflow Engine API. ## Current State - 159 API endpoints across 33 blueprint files - No OpenAPI/Swagger implementation exists - Using Quart (async Flask) framework - Pydantic 2.0+ already installed ## Requirements ### 1. Choose and Install OpenAPI Library Options for Quart: - **quart-schema** - Quart-native, good Pydantic support - **spectree** - Modern, works with Quart/Flask, excellent Pydantic 2.0 support - **apispec** + **apispec-webframeworks** - Generic, requires more manual work **Recommendation:** spectree with Pydantic for automatic schema generation ### 2. Create Base Infrastructure ```python # api/openapi/__init__.py from spectree import SpecTree spec = SpecTree( 'quart', title='Highway Workflow Engine API', version='1.0.0', path='openapi', # /openapi/redoc, /openapi/swagger security_schemes=[ {'name': 'Bearer', 'type': 'http', 'scheme': 'bearer'} ] ) ``` ### 3. Create Base Response/Request Models ```python # api/openapi/models/base.py from pydantic import BaseModel class SuccessResponse(BaseModel): status: str = 'success' data: dict | list | None = None class ErrorResponse(BaseModel): status: str = 'error' message: str code: str ``` ### 4. Set Up Swagger UI and ReDoc - /api/v1/docs (Swagger UI) - /api/v1/redoc (ReDoc) - /api/v1/openapi.json (Raw spec) ## Files to Create - api/openapi/__init__.py - api/openapi/models/__init__.py - api/openapi/models/base.py - api/openapi/models/common.py (pagination, errors) ## Dependencies to Add ```toml spectree>=1.0.0 ``` ## Acceptance Criteria - [ ] OpenAPI library integrated with Quart app - [ ] Swagger UI accessible at /api/v1/docs - [ ] ReDoc accessible at /api/v1/redoc - [ ] Base response models created - [ ] Authentication scheme documented - [ ] All existing endpoints still work