feat(api): publish OpenAPI 3.x spec + spectral CI lint gate

.github/workflows/build.yml

@@ -14,6 +14,8 @@ on:
       - '.version'
       - '.github/workflows/build.yml'
       - 'services/flask-backend/requirements.txt'
+      - 'services/flask-backend/openapi/**'
+      - 'services/flask-backend/.spectral.yaml'
   pull_request:
     branches:
       - main
@@ -26,6 +28,8 @@ on:
       - '.version'
       - '.github/workflows/build.yml'
       - 'services/flask-backend/requirements.txt'
+      - 'services/flask-backend/openapi/**'
+      - 'services/flask-backend/.spectral.yaml'
 
 permissions:
   contents: read
@@ -109,6 +113,11 @@ jobs:
       - name: Run flake8
         run: flake8 services/flask-backend/app/ tests/smoke/ --count --select=E9,F63,F7,F82 --show-source
 
+      - name: Validate OpenAPI specification
+        run: |
+          npm install -g @stoplight/spectral-cli@latest
+          spectral lint services/flask-backend/openapi/v1.yaml
+
   test:
     name: Run Tests
     runs-on: ubuntu-latest

.gitignore

@@ -1,3 +1,6 @@
+# Git worktrees (repo-local, per {repo}/worktrees/{branch} convention)
+/worktrees/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

Makefile

@@ -1,7 +1,7 @@
 # Project Template Makefile
 # This Makefile provides common development tasks for multi-language projects
 
-.PHONY: help setup dev test build clean lint format docker deploy test-e2e test-e2e-api test-e2e-ui test-functional smoke-test seed-mock-data
+.PHONY: help setup dev test build clean lint format docker deploy test-e2e test-e2e-api test-e2e-ui test-functional smoke-test seed-mock-data openapi-lint
 
 # Default target
 .DEFAULT_GOAL := help
@@ -261,6 +261,16 @@ lint-node: ## Code Quality - Run Node.js linting
 	@npm run lint
 	@cd web && npm run lint
 
+openapi-lint: ## Code Quality - Validate OpenAPI specs with spectral
+	@echo "$(BLUE)Validating OpenAPI specification...$(RESET)"
+	@if command -v spectral >/dev/null 2>&1; then \
+		spectral lint services/flask-backend/openapi/v1.yaml; \
+	else \
+		echo "$(YELLOW)spectral not found, trying npx...$(RESET)"; \
+		npx -y @stoplight/spectral-cli@latest lint services/flask-backend/openapi/v1.yaml; \
+	fi
+	@echo "$(GREEN)OpenAPI validation complete!$(RESET)"
+
 format: ## Code Quality - Format code for all languages
 	@echo "$(BLUE)Formatting code...$(RESET)"
 	@$(MAKE) format-go

services/flask-backend/.spectral.yaml

@@ -0,0 +1 @@
+extends: spectral:oas

services/flask-backend/app/__init__.py

@@ -38,6 +38,9 @@ def create_app(config_class: type | None = None) -> Quart:
 
     Returns:
         Configured Quart application instance
+
+    Raises:
+        ValueError: If production config validation fails (missing or invalid secrets)
     """
     app = Quart(__name__)
 
@@ -46,6 +49,10 @@ def create_app(config_class: type | None = None) -> Quart:
         config_class = get_config()
     app.config.from_object(config_class)
 
+    # Validate configuration (production only)
+    if hasattr(config_class, "validate"):
+        config_class.validate()
+
     # Setup logging
     _setup_logging(app)
 
@@ -73,6 +80,11 @@ def create_app(config_class: type | None = None) -> Quart:
 
     init_licensing(app)
 
+    # Initialize rate limiter
+    from .rate_limiter import init_rate_limiter
+
+    init_rate_limiter(app)
+
     # Apply security headers middleware
     _apply_security_headers(app)
 
@@ -250,6 +262,23 @@ def _register_blueprints(app: Quart) -> None:
 
     app.register_blueprint(tenants_bp, url_prefix="/api/v1")
 
+    # URL shortener management (Phase 3)
+    from .urls import urls_bp
+    from .collections import collections_bp
+
+    app.register_blueprint(urls_bp, url_prefix="/api/v1")
+    app.register_blueprint(collections_bp, url_prefix="/api/v1")
+
+    # Redirect endpoint (public, at root — NO auth required)
+    from .redirect import redirect_bp
+
+    app.register_blueprint(redirect_bp)
+
+    # Analytics endpoints (Phase 3 — auth required)
+    from .analytics import analytics_bp
+
+    app.register_blueprint(analytics_bp)
+
     # OAuth2 token endpoints (Phase 2)
     from .oauth import oauth_bp