init commit

templates/openapi/generate_docs.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+
+# vStash OpenAPI Documentation Generator
+# This script compiles the OpenAPI YAML files and generates HTML documentation
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🚀 vStash API Documentation Generator${NC}"
+echo "================================================"
+
+# Check if we're in the right directory
+if [ ! -f "templates/openapi/v1.yaml" ]; then
+    echo -e "${RED}❌ Error: templates/openapi/v1.yaml not found${NC}"
+    echo "Please run this script from the project root directory"
+    exit 1
+fi
+
+cd templates/openapi
+
+# Check for required tools
+echo -e "${BLUE}🔍 Checking dependencies...${NC}"
+
+if ! command -v redocly &> /dev/null; then
+    echo -e "${YELLOW}⚠️  redocly not found. Installing...${NC}"
+    npm install -g @redocly/cli@latest
+fi
+
+# Try to install modern swagger tools
+if ! command -v swagger-cli &> /dev/null; then
+    echo -e "${YELLOW}⚠️  swagger-cli not found. Installing modern version...${NC}"
+    npm install -g @apidevtools/swagger-cli
+fi
+
+echo -e "${GREEN}✅ Dependencies check complete${NC}"
+
+# Create output directory
+mkdir -p html
+
+# Step 1: Bundle YAML files
+echo -e "${BLUE}📦 Bundling YAML files...${NC}"
+
+# Try redocly first (better multi-file support)
+if redocly bundle v1.yaml --output openapi.yaml; then
+    echo -e "${GREEN}✅ YAML bundling complete (using redocly)${NC}"
+fi
+
+# Step 2: Validate the bundled YAML
+echo -e "${BLUE}🔍 Validating OpenAPI specification...${NC}"
+redocly lint openapi.yaml
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✅ OpenAPI validation passed${NC}"
+else
+    echo -e "${YELLOW}⚠️  OpenAPI validation warnings (proceeding anyway)${NC}"
+fi
+
+# Step 3: Generate HTML documentation
+echo -e "${BLUE}📖 Generating HTML documentation...${NC}"
+redocly build-docs openapi.yaml --output=html/index.html
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✅ HTML documentation generated${NC}"
+else
+    echo -e "${RED}❌ HTML documentation generation failed${NC}"
+    exit 1
+fi
+
+# Step 4: Generate additional formats (optional)
+echo -e "${BLUE}📄 Generating additional documentation formats...${NC}"
+
+# Generate a cleaner JSON version
+if command -v yq &> /dev/null; then
+    yq eval openapi.yaml -o=json > openapi.json
+    echo -e "${GREEN}✅ JSON format generated${NC}"
+else
+    echo -e "${YELLOW}⚠️  yq not found, skipping JSON generation${NC}"
+fi
+
+echo ""
+echo -e "${GREEN}🎉 Documentation generation complete!${NC}"
+echo "================================================"
+echo -e "${BLUE}📁 Generated files:${NC}"
+echo "  • templates/openapi/openapi.yaml (bundled spec)"
+echo "  • templates/openapi/openapi.json (JSON format)"
+echo "  • templates/openapi/html/index.html (main docs)"
+echo ""
+echo -e "${BLUE}🌐 To view the documentation:${NC}"
+echo "  Local: file://$(pwd)/html/index.html"
+echo "  Or serve with: python -m http.server 8080 -d html"
+echo ""
+echo -e "${BLUE}📋 Next steps:${NC}"
+echo "  1. Review the generated documentation"
+echo "  2. Deploy html/index.html to your web server"
+echo "  3. Update API endpoints if needed"
+echo "  4. Share with your team!"
+echo ""
+
+# Optional: Open documentation in browser (macOS/Linux)
+if command -v open &> /dev/null; then
+    read -p "Open documentation in browser? (y/n): " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        open html/index.html
+    fi
+elif command -v xdg-open &> /dev/null; then
+    read -p "Open documentation in browser? (y/n): " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        xdg-open html/index.html
+    fi
+fi
+
+echo -e "${GREEN}✨ All done!${NC}"