vstash/templates/openapi/generate_docs.sh

#!/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}"