120 lines
3.6 KiB
Bash
Executable File
120 lines
3.6 KiB
Bash
Executable File
#!/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}" |