feat: upgrade to Swagger UI 5.30.2 and unify URL parameter

README.md

@@ -3,7 +3,7 @@
 A simple and elegant OpenAPI/Swagger documentation viewer hosted on GitHub Pages. Supports dynamic loading of any public API specification files.
 
 [![GitHub Pages](https://img.shields.io/badge/demo-GitHub%20Pages-blue)](https://min0625.github.io/openapi-viewer/)
-[![Swagger UI](https://img.shields.io/badge/Swagger%20UI-5.10.0-green)](https://github.com/swagger-api/swagger-ui)
+[![Swagger UI](https://img.shields.io/badge/Swagger%20UI-5.30.2-green)](https://github.com/swagger-api/swagger-ui)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 [繁體中文](./README.zh-TW.md) | English
@@ -22,45 +22,45 @@ A simple and elegant OpenAPI/Swagger documentation viewer hosted on GitHub Pages
 
 ### Method 1: Load External API Documentation
 
-Add the `?uri=` parameter to the URL, pointing to your OpenAPI/Swagger JSON file:
+Add the `?url=` parameter to the URL, pointing to your OpenAPI/Swagger JSON file:
 
 ```
-https://min0625.github.io/openapi-viewer?uri=https://petstore3.swagger.io/api/v3/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://petstore3.swagger.io/api/v3/openapi.json
 ```
 
 ### Method 2: Load Files from GitHub
 
 Use GitHub Raw URL:
 
 ```
-https://min0625.github.io/openapi-viewer?uri=https://raw.githubusercontent.com/username/repo/main/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://raw.githubusercontent.com/min0625/openapi-viewer/main/swagger.json
 ```
 
-### Method 3: No URI Parameter
+### Method 3: No URL Parameter
 
-If you visit without the `uri` parameter, you'll see a helpful guide on how to use the viewer.
+If you visit without the `url` parameter, the default example API documentation will be loaded.
 
 ## 📚 Usage Examples
 
 ### Swagger 2.0 Example
 ```
-https://min0625.github.io/openapi-viewer?uri=https://petstore.swagger.io/v2/swagger.json
+https://min0625.github.io/openapi-viewer?url=https://petstore.swagger.io/v2/swagger.json
 ```
 
 ### OpenAPI 3.0 Example
 ```
-https://min0625.github.io/openapi-viewer?uri=https://petstore3.swagger.io/api/v3/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://petstore3.swagger.io/api/v3/openapi.json
 ```
 
 ### Load from Private Gist
 ```
-https://min0625.github.io/openapi-viewer?uri=https://gist.githubusercontent.com/username/gist-id/raw/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://gist.githubusercontent.com/username/gist-id/raw/openapi.json
 ```
 
 ## 🛠️ Technical Specifications
 
-- **Swagger UI**: v5.10.0
-- **Supported Formats**: 
+- **Swagger UI**: v5.30.2
+- **Supported Formats**:
   - Swagger 2.0 (JSON/YAML)
   - OpenAPI 3.0.x (JSON/YAML)
   - OpenAPI 3.1.x (JSON/YAML)
@@ -98,11 +98,26 @@ You can fork this project and modify `index.html` to:
 ## ⚠️ Important Notes
 
 ### CORS Limitations
-The loaded API documentation must allow cross-origin requests (CORS). If you encounter CORS errors:
 
-1. Ensure the target server has proper CORS headers configured
-2. Use GitHub Raw URLs or GitHub Gist
-3. Use CORS-enabled CDN services
+The loaded API documentation must allow cross-origin requests (CORS). If you encounter CORS errors, consider these solutions:
+
+#### 📝 Recommended Solutions
+
+1. **Use GitHub Raw URL**: Recommended approach, no CORS restrictions
+   ```
+   https://raw.githubusercontent.com/<user>/<repo>/<branch>/<path-to-file>
+   ```
+
+2. **Use GitHub Gist**: Great for sharing example documentation
+   ```
+   https://gist.githubusercontent.com/<user>/<gist-id>/raw/<file>
+   ```
+
+3. **Configure Server CORS**: If you control the API server, add these headers:
+   ```
+   Access-Control-Allow-Origin: *
+   Access-Control-Allow-Methods: GET, OPTIONS
+   ```
 
 ### GitHub Raw URL Format
 When using GitHub files, use the following format:
@@ -138,4 +153,4 @@ If you have any questions or suggestions:
 
 ---
 
-<p align="center">Made with ❤️ by <a href="https://github.com/min0625">Min Huang</a></p>
+<p align="center">Made with ❤️ by <a href="https://github.com/min0625">Min Huang</a></p>

README.zh-TW.md

@@ -3,7 +3,7 @@
 一個簡潔優雅的 OpenAPI/Swagger 文件檢視器,透過 GitHub Pages 託管,支援動態載入任何公開的 API 規格文件。
 
 [![GitHub Pages](https://img.shields.io/badge/demo-GitHub%20Pages-blue)](https://min0625.github.io/openapi-viewer/)
-[![Swagger UI](https://img.shields.io/badge/Swagger%20UI-5.10.0-green)](https://github.com/swagger-api/swagger-ui)
+[![Swagger UI](https://img.shields.io/badge/Swagger%20UI-5.30.2-green)](https://github.com/swagger-api/swagger-ui)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 繁體中文 | [English](./README.md)
@@ -22,45 +22,45 @@
 
 ### 方式 1: 載入外部 API 文件
 
-在 URL 後加上 `?uri=` 參數,指向你的 OpenAPI/Swagger JSON 檔案:
+在 URL 後加上 `?url=` 參數，指向你的 OpenAPI/Swagger JSON 檔案：
 
 ```
-https://min0625.github.io/openapi-viewer?uri=https://petstore3.swagger.io/api/v3/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://petstore3.swagger.io/api/v3/openapi.json
 ```
 
 ### 方式 2: 載入 GitHub 上的檔案
 
-使用 GitHub Raw URL:
+使用 GitHub Raw URL：
 
 ```
-https://min0625.github.io/openapi-viewer?uri=https://raw.githubusercontent.com/username/repo/main/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://raw.githubusercontent.com/min0625/openapi-viewer/main/swagger.json
 ```
 
-### 方式 3: 不提供 URI 參數
+### 方式 3: 不提供 URL 參數
 
-如果直接訪問而不帶 `uri` 參數,會顯示使用說明引導頁面。
+如果直接訪問而不帶 `url` 參數，會載入預設的範例 API 文件。
 
 ## 📚 使用範例
 
 ### Swagger 2.0 範例
 ```
-https://min0625.github.io/openapi-viewer?uri=https://petstore.swagger.io/v2/swagger.json
+https://min0625.github.io/openapi-viewer?url=https://petstore.swagger.io/v2/swagger.json
 ```
 
 ### OpenAPI 3.0 範例
 ```
-https://min0625.github.io/openapi-viewer?uri=https://petstore3.swagger.io/api/v3/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://petstore3.swagger.io/api/v3/openapi.json
 ```
 
 ### 載入私有 Gist
 ```
-https://min0625.github.io/openapi-viewer?uri=https://gist.githubusercontent.com/username/gist-id/raw/openapi.json
+https://min0625.github.io/openapi-viewer?url=https://gist.githubusercontent.com/username/gist-id/raw/openapi.json
 ```
 
 ## 🛠️ 技術規格
 
-- **Swagger UI**: v5.10.0
-- **支援格式**: 
+- **Swagger UI**: v5.30.2
+- **支援格式**:
   - Swagger 2.0 (JSON/YAML)
   - OpenAPI 3.0.x (JSON/YAML)
   - OpenAPI 3.1.x (JSON/YAML)
@@ -98,14 +98,29 @@ npx serve .
 ## ⚠️ 注意事項
 
 ### CORS 限制
-載入的 API 文件必須允許跨域請求 (CORS)。如果遇到 CORS 錯誤:
 
-1. 確保目標伺服器設定了正確的 CORS headers
-2. 使用 GitHub Raw URL 或 GitHub Gist
-3. 使用支援 CORS 的 CDN 服務
+載入的 API 文件必須允許跨域請求 (CORS)。如果遇到 CORS 錯誤，請考慮以下解決方案：
+
+#### � 推薦解決方案
+
+1. **使用 GitHub Raw URL**: 推薦的方式，沒有 CORS 限制
+   ```
+   https://raw.githubusercontent.com/<user>/<repo>/<branch>/<path-to-file>
+   ```
+
+2. **使用 GitHub Gist**: 適合分享範例文件
+   ```
+   https://gist.githubusercontent.com/<user>/<gist-id>/raw/<file>
+   ```
+
+3. **配置伺服器 CORS**: 如果你控制 API 伺服器，添加以下 headers:
+   ```
+   Access-Control-Allow-Origin: *
+   Access-Control-Allow-Methods: GET, OPTIONS
+   ```
 
 ### GitHub Raw URL 格式
-使用 GitHub 檔案時,使用以下格式:
+使用 GitHub 檔案時，使用以下格式：
 ```
 https://raw.githubusercontent.com/<user>/<repo>/<branch>/<path-to-file>
 ```
@@ -138,4 +153,4 @@ https://raw.githubusercontent.com/<user>/<repo>/<branch>/<path-to-file>
 
 ---
 
-<p align="center">Made with ❤️ by <a href="https://github.com/min0625">Min Huang</a></p>
+<p align="center">Made with ❤️ by <a href="https://github.com/min0625">Min Huang</a></p>

index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>OpenAPI Viewer</title>
-    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.10.0/swagger-ui.css">
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.30.2/swagger-ui.css">
     <style>
         html {
             box-sizing: border-box;
@@ -38,17 +38,8 @@
             max-width: 90%;
         }
 
-        #info-banner {
-            background-color: #2196F3;
-            color: white;
-            padding: 10px 20px;
-            text-align: center;
-            font-family: sans-serif;
-            font-size: 14px;
-        }
-
         #placeholder {
-            display: flex;
+            display: none;
             flex-direction: column;
             align-items: center;
             justify-content: center;
@@ -72,17 +63,17 @@
     </style>
 </head>
 <body>
-    <div id="info-banner">
-        🔍 Supports Swagger 2.0 & OpenAPI 3.x | Usage: ?uri=your-openapi-url
-    </div>
     <div id="error-message"></div>
     <div id="placeholder"></div>
+    <div id="loading" style="display:none; text-align:center; padding: 24px; font-family: sans-serif; color:#666">
+        <h3>⏳ Loading API documentation...</h3>
+        <p id="loading-status"></p>
+    </div>
     <div id="swagger-ui"></div>
 
-    <script src="https://unpkg.com/swagger-ui-dist@5.10.0/swagger-ui-bundle.js"></script>
-    <script src="https://unpkg.com/swagger-ui-dist@5.10.0/swagger-ui-standalone-preset.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5.30.2/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5.30.2/swagger-ui-standalone-preset.js"></script>
     <script>
-        // Display error message
         function showError(message) {
             const errorDiv = document.getElementById('error-message');
             errorDiv.textContent = message;
@@ -92,28 +83,29 @@
             }, 5000);
         }
 
+        function setLoading(show, msg) {
+            const loading = document.getElementById('loading');
+            const status = document.getElementById('loading-status');
+            if (loading) loading.style.display = show ? 'block' : 'none';
+            if (status && msg) status.textContent = msg;
+        }
+
         window.onload = function() {
-            // Get swagger.json location from URL parameter
+            const DEFAULT_SPEC_URL = 'https://raw.githubusercontent.com/min0625/openapi-viewer/main/swagger.json';
             const urlParams = new URLSearchParams(window.location.search);
-            const swaggerUri = urlParams.get('uri');
+            let swaggerUrl = urlParams.get('url');
 
-            // If no uri parameter provided, show helpful message
-            if (!swaggerUri) {
-                const placeholder = document.getElementById('placeholder');
-                placeholder.innerHTML = `
-                    <h2>⚠️ Please provide an API documentation URL</h2>
-                    <p>Usage:</p>
-                    <p><code>?uri=https://example.com/openapi.json</code></p>
-                    <br>
-                    <p>Example:</p>
-                    <p><code>?uri=https://petstore3.swagger.io/api/v3/openapi.json</code></p>
-                `;
-                return;
+            if (!swaggerUrl) {
+                swaggerUrl = DEFAULT_SPEC_URL;
+                console.log('ℹ️ No url parameter provided. Using default spec:', swaggerUrl);
             }
 
+            console.log('🔍 Loading from:', swaggerUrl);
+            setLoading(true, 'Initializing Swagger UI...');
+
             try {
                 const ui = SwaggerUIBundle({
-                    url: swaggerUri,
+                    url: swaggerUrl,
                     dom_id: '#swagger-ui',
                     deepLinking: true,
                     presets: [
@@ -124,35 +116,33 @@ <h2>⚠️ Please provide an API documentation URL</h2>
                         SwaggerUIBundle.plugins.DownloadUrl
                     ],
                     layout: "StandaloneLayout",
-                    // Support both Swagger 2.0 and OpenAPI 3.x
-                    validatorUrl: null, // Disable online validator to support private docs
+                    validatorUrl: null,
                     onComplete: function() {
-                        // Detect specification version
-                        const spec = ui.getState().toJS().spec.json;
-                        let version = 'Unknown';
-
-                        if (spec.swagger) {
-                            version = `Swagger ${spec.swagger}`;
-                        } else if (spec.openapi) {
-                            version = `OpenAPI ${spec.openapi}`;
-                        }
-
-                        console.log(`✅ Successfully loaded ${version} specification`);
-                        document.getElementById('info-banner').innerHTML =
-                            `🔍 Supports Swagger 2.0 & OpenAPI 3.x | Current version: <strong>${version}</strong>`;
+                        setLoading(false);
+                        console.log('✅ Successfully initialized');
                     },
                     onFailure: function(error) {
-                        console.error('Loading failed:', error);
-                        showError('❌ Failed to load API documentation: ' + error.message);
+                        setLoading(false);
+                        console.error('❌ onFailure:', error);
+                        showError('Failed to load API documentation: ' + (error.message || error));
                     }
                 });
 
                 window.ui = ui;
             } catch (error) {
-                console.error('Initialization failed:', error);
-                showError('❌ Failed to initialize Swagger UI: ' + error.message);
+                setLoading(false);
+                console.error('❌ Initialization error:', error);
+                showError('Failed to initialize: ' + error.message);
+
+                const placeholder = document.getElementById('placeholder');
+                placeholder.style.display = 'flex';
+                placeholder.innerHTML = `
+                    <h2>❌ Failed to load API documentation</h2>
+                    <p><strong>Error:</strong> ${error.message}</p>
+                    <p><strong>URL:</strong> <code>${swaggerUrl}</code></p>
+                `;
             }
         };
     </script>
 </body>
-</html>
+</html>