Convert Green Button API from Swagger 1.2 to OpenAPI 3.0

[dfcoffin]

Summary

This PR converts the complete Green Button (ESPI) API definition from Swagger 1.2 to OpenAPI 3.0.0 with comprehensive documentation, examples, and automated CI/CD.

What's Changed

🔄 API Conversion

• ✅ Converted 11 Swagger 1.2 API declarations to OpenAPI 3.0 format
• ✅ Created 16 schema files from XSD definitions (atom.xsd, espi.xsd, customer_4.1.xsd)
• ✅ Added 7 reusable parameter components for common query parameters
• ✅ Defined OAuth2 security scheme with authorizationCode and clientCredentials flows
• ✅ Created 27 path files covering all Green Button API endpoints

📚 Documentation & Examples

• ✅ Added comprehensive XML response examples extracted from real ESPI sample data
• ✅ Included 5 named examples for AtomEntry responses (UsagePoint, LocalTimeParameters, MeterReading, ReadingType, IntervalBlock)
• ✅ Included 3 named examples for AtomFeed responses (Subscription feed, collection feeds)
• ✅ Properly annotated XML namespaces (Atom: http://www.w3.org/2005/Atom, ESPI: http://naesb.org/espi)

🤖 CI/CD Pipeline

• ✅ Added GitHub Actions workflow for automated validation
• ✅ Runs OpenAPI lint checks on all PRs
• ✅ Validates spec can be bundled successfully
• ✅ Auto-deploys documentation to GitHub Pages on main branch pushes
• ✅ Uploads bundled specs as artifacts (30-day retention)

🛠️ Configuration

• ✅ Updated .gitignore to exclude .idea and .claude directories
• ✅ Configured Redocly to handle XML examples for application/atom+xml content type

Resources Converted

• ApplicationInformation
• Authorization
• Batch (Bulk, Subscription, RetailCustomer endpoints)
• UsagePoint
• MeterReading
• ReadingType
• IntervalBlock
• LocalTimeParameters
• ElectricPowerQualitySummary
• UsageSummary
• ServiceStatus

Validation

✅ Passes all checks: npx @redocly/cli lint returns zero errors and zero warnings

Files Changed

• 74 files changed
• 3,275 insertions
• 837 deletions

Breaking Changes

⚠️ This PR replaces the example OpenAPI starter content with the actual Green Button API definition. The example schemas (User, Admin, etc.) and paths (echo, user-status, etc.) have been removed.

Next Steps After Merge

1. Enable GitHub Pages in repository settings (Settings → Pages → Source: GitHub Actions)
2. Documentation will be available at: https://greenbuttonalliance.github.io/openapi-starter/
3. CI/CD will automatically validate all future PRs

Testing

npm test        # Validates the OpenAPI spec
npm run build   # Bundles the specification
npm start       # Previews the documentation locally

---

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