GreenButtonAlliance · dfcoffin · Feb 7, 2026 · Feb 7, 2026
diff --git a/README.md b/README.md
@@ -14,14 +14,39 @@
 ### Usage
 
 #### `npm start`
-Starts the reference docs preview server.
+Starts the Redocly reference docs preview server.
+
+#### `npm start:swagger`
+Starts a local server to preview Swagger UI (requires building first).
 
 #### `npm run build`
-Bundles the definition to the dist folder.
+Builds both Redocly documentation and Swagger UI to the dist folder.
+
+#### `npm run build:redocly`
+Builds only the Redocly documentation.
+
+#### `npm run build:swagger`
+Builds only the Swagger UI.
 
 #### `npm test`
 Validates the definition.
 
+## Documentation Formats
+
+This repository generates two types of API documentation:
+
+### Redocly (Main Documentation)
+- **Location:** `dist/index.html`
+- **Live:** https://greenbuttonalliance.github.io/openapi-starter/
+- **Purpose:** Beautiful, readable API documentation
+- **Features:** Clean layout, Green Button theming, comprehensive examples
+
+### Swagger UI (Interactive Explorer)
+- **Location:** `dist/swagger/index.html`
+- **Live:** https://greenbuttonalliance.github.io/openapi-starter/swagger/
+- **Purpose:** Interactive API testing and exploration
+- **Features:** "Try it out" functionality, request/response testing, OAuth flow
+
 ## Contribution Guide
 
 Below is a sample contribution guide. The tools

diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml
@@ -9,6 +9,9 @@ info:
     to exchange energy usage information using Atom-formatted XML feeds.
 
 
+    **Interactive API Explorer:** Try out the API using [Swagger UI](./swagger/)
+
+
     All resources are returned as Atom feeds (collections) or Atom entries
     (individual resources) using the `application/atom+xml` content type.
     The ESPI data elements are embedded within the Atom `<content>` element

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -7,8 +7,14 @@
   "private": true,
   "scripts": {
     "start": "redocly preview-docs",
-    "build": "redocly build-docs openapi/openapi.yaml -o dist/index.html",
-    "bundle": "redocly bundle openapi/openapi.yaml -o dist/bundle.yaml",
+    "start:swagger": "npx http-server dist -p 8081",
+    "build": "npm run build:redocly && npm run build:swagger",
+    "build:redocly": "redocly build-docs openapi/openapi.yaml -o dist/index.html",
+    "build:swagger": "npm run bundle && node scripts/build-swagger.js",
+    "bundle": "redocly bundle openapi/openapi.yaml -o dist/openapi.json",
     "test": "redocly lint"
+  },
+  "devDependencies": {
+    "swagger-ui-dist": "^5.31.0"
   }
 }
diff --git a/scripts/build-swagger.js b/scripts/build-swagger.js
@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+// Create dist/swagger directory
+const swaggerDir = path.join(__dirname, '..', 'dist', 'swagger');
+if (!fs.existsSync(swaggerDir)) {
+  fs.mkdirSync(swaggerDir, { recursive: true });
+}
+
+// Copy Swagger UI assets
+const swaggerUiPath = path.join(__dirname, '..', 'node_modules', 'swagger-ui-dist');
+const files = fs.readdirSync(swaggerUiPath);
+
+files.forEach(file => {
+  if (file.endsWith('.js') || file.endsWith('.css') || file.endsWith('.map') || file.endsWith('.png')) {
+    fs.copyFileSync(
+      path.join(swaggerUiPath, file),
+      path.join(swaggerDir, file)
+    );
+  }
+});
+
+// Copy bundled OpenAPI spec
+fs.copyFileSync(
+  path.join(__dirname, '..', 'dist', 'openapi.json'),
+  path.join(swaggerDir, 'openapi.json')
+);
+
+// Create custom Swagger UI HTML with Green Button branding
+const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Green Button ESPI API - Swagger UI</title>
+  <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
+  <link rel="icon" type="image/png" href="../../logo.png" />
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *, *:before, *:after {
+      box-sizing: inherit;
+    }
+    body {
+      margin: 0;
+      padding: 0;
+    }
+    .topbar {
+      background-color: #10a54a !important;
+    }
+    .topbar .link {
+      display: flex;
+      align-items: center;
+    }
+    .topbar .link img {
+      max-height: 40px;
+      margin-right: 10px;
+    }
+    .swagger-ui .topbar .download-url-wrapper {
+      display: flex;
+      align-items: center;
+    }
+    .swagger-ui .topbar .download-url-wrapper .download-url-button {
+      background-color: #0d8c3e !important;
+    }
+    .swagger-ui .btn.authorize {
+      background-color: #10a54a !important;
+      border-color: #10a54a !important;
+    }
+    .swagger-ui .btn.execute {
+      background-color: #10a54a !important;
+      border-color: #10a54a !important;
+    }
+    /* Link to Redocly docs */
+    .custom-nav {
+      position: fixed;
+      top: 60px;
+      right: 20px;
+      z-index: 1000;
+      background: white;
+      padding: 10px 20px;
+      border-radius: 4px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+    .custom-nav a {
+      color: #10a54a;
+      text-decoration: none;
+      font-weight: 600;
+    }
+    .custom-nav a:hover {
+      text-decoration: underline;
+    }
+  </style>
+</head>
+<body>
+  <div class="custom-nav">
+    <a href="../index.html">📖 View Documentation (Redocly)</a>
+  </div>
+  <div id="swagger-ui"></div>
+  <script src="./swagger-ui-bundle.js"></script>
+  <script src="./swagger-ui-standalone-preset.js"></script>
+  <script>
+    window.onload = function() {
+      window.ui = SwaggerUIBundle({
+        url: "./openapi.json",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout",
+        // Green Button Alliance branding
+        customSiteTitle: "Green Button ESPI API",
+        tryItOutEnabled: true
+      });
+    };
+  </script>
+</body>
+</html>`;
+
+fs.writeFileSync(path.join(swaggerDir, 'index.html'), html);
+
+console.log('✅ Swagger UI built successfully at dist/swagger/');
+console.log('   - Redocly docs: dist/index.html');
+console.log('   - Swagger UI: dist/swagger/index.html');