Add Swagger UI alongside Redocly documentation

[dfcoffin]

Summary

Adds Swagger UI for interactive API exploration alongside the existing Redocly documentation, providing users with two complementary ways to interact with the Green Button ESPI API.

Problem Solved

Users need different tools for different purposes:

• Documentation readers → Redocly (beautiful, comprehensive)
• API testers/developers → Swagger UI (interactive, "try it out")

Both tools now use the same openapi/openapi.yaml source file - no duplication!

Changes Made

1. Added Swagger UI

✅ Installed swagger-ui-dist package
✅ Created build script (scripts/build-swagger.js)
✅ Green Button branded - Custom colors and styling
✅ Navigation - Link from Swagger UI to Redocly docs

2. Updated Build System

✅ npm run build - Builds both formats
✅ npm run build:redocly - Builds only Redocly
✅ npm run build:swagger - Builds only Swagger UI
✅ npm run bundle - Generates JSON bundle for Swagger

3. Documentation Updates

✅ Updated README with both documentation formats
✅ Added link in OpenAPI description to Swagger UI
✅ Cross-navigation between both interfaces

Documentation Formats

Redocly (Main) - dist/index.html

• 📖 Beautiful, readable documentation
• 🎨 Green Button theming
• 📝 Comprehensive XML examples
• 🔍 Search functionality
• Live: https://greenbuttonalliance.github.io/openapi-starter/

Swagger UI (Interactive) - dist/swagger/index.html

• 🧪 Interactive API testing
• ▶️ "Try it out" functionality
• 🔐 OAuth 2.0 flow testing
• 📤 Request/response examples
• Live: https://greenbuttonalliance.github.io/openapi-starter/swagger/

Build Output Structure

dist/
├── index.html              # Redocly documentation (959 KiB)
├── openapi.json           # Bundled spec for Swagger UI (192 KiB)
├── bundle.yaml            # YAML bundle
└── swagger/
    ├── index.html         # Swagger UI
    ├── swagger-ui.css     # UI styles
    ├── swagger-ui-bundle.js
    └── openapi.json       # API spec

File Changes

• Added: scripts/build-swagger.js (build script)
• Modified: package.json (new scripts, swagger-ui-dist dep)
• Modified: package-lock.json (new dependencies)
• Modified: README.md (documentation for both formats)
• Modified: openapi/openapi.yaml (link to Swagger UI)

Total: 5 files changed, 191 insertions, 4 deletions

Features

Green Button Branding

• Custom colors (#10a54a green)
• Logo integration
• Branded topbar
• Custom button styles

Cross-Navigation

• Swagger UI → "📖 View Documentation (Redocly)"
• Redocly → "Interactive API Explorer (Swagger UI)"

Single Source of Truth

Both tools read from openapi/openapi.yaml - maintain one file, get two interfaces!

Validation

✅ npm test - Passes with valid OpenAPI spec
✅ npm run build - Successfully builds both formats
✅ Both interfaces display correctly

Testing

After merge, verify:

1. Redocly: https://greenbuttonalliance.github.io/openapi-starter/
2. Swagger UI: https://greenbuttonalliance.github.io/openapi-starter/swagger/
3. Navigation links work between both

---

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com