From e9ee9363af1604a0678fb1773ed3c1a0f0c7a0e2 Mon Sep 17 00:00:00 2001 From: min0625 <70873102+min0625@users.noreply.github.com> Date: Wed, 5 Nov 2025 01:45:02 +0800 Subject: [PATCH 1/2] docs: update README and index.html --- README.md | 6 +++--- README.zh-TW.md | 6 +++--- index.html | 19 +++---------------- 3 files changed, 9 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 21c9476..47c5810 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ https://min0625.github.io/openapi-viewer?uri=https://petstore3.swagger.io/api/v3 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?uri=https://raw.githubusercontent.com/min0625/openapi-viewer/refs/heads/main/swagger.json ``` ### Method 3: No URI Parameter @@ -60,7 +60,7 @@ https://min0625.github.io/openapi-viewer?uri=https://gist.githubusercontent.com/ ## 🛠️ Technical Specifications - **Swagger UI**: v5.10.0 -- **Supported Formats**: +- **Supported Formats**: - Swagger 2.0 (JSON/YAML) - OpenAPI 3.0.x (JSON/YAML) - OpenAPI 3.1.x (JSON/YAML) @@ -138,4 +138,4 @@ If you have any questions or suggestions: --- -

Made with ❤️ by Min Huang

\ No newline at end of file +

Made with ❤️ by Min Huang

diff --git a/README.zh-TW.md b/README.zh-TW.md index 69eaa1f..1bffd46 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -33,7 +33,7 @@ https://min0625.github.io/openapi-viewer?uri=https://petstore3.swagger.io/api/v3 使用 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?uri=https://raw.githubusercontent.com/min0625/openapi-viewer/refs/heads/main/swagger.json ``` ### 方式 3: 不提供 URI 參數 @@ -60,7 +60,7 @@ https://min0625.github.io/openapi-viewer?uri=https://gist.githubusercontent.com/ ## 🛠️ 技術規格 - **Swagger UI**: v5.10.0 -- **支援格式**: +- **支援格式**: - Swagger 2.0 (JSON/YAML) - OpenAPI 3.0.x (JSON/YAML) - OpenAPI 3.1.x (JSON/YAML) @@ -138,4 +138,4 @@ https://raw.githubusercontent.com//// --- -

Made with ❤️ by Min Huang

\ No newline at end of file +

Made with ❤️ by Min Huang

diff --git a/index.html b/index.html index afdb386..59ae224 100644 --- a/index.html +++ b/index.html @@ -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,9 +63,6 @@ -
- 🔍 Supports Swagger 2.0 & OpenAPI 3.x | Usage: ?uri=your-openapi-url -
@@ -100,6 +88,7 @@ // If no uri parameter provided, show helpful message if (!swaggerUri) { const placeholder = document.getElementById('placeholder'); + placeholder.style.display = 'flex'; placeholder.innerHTML = `

⚠️ Please provide an API documentation URL

Usage:

@@ -138,8 +127,6 @@

⚠️ Please provide an API documentation URL

} console.log(`✅ Successfully loaded ${version} specification`); - document.getElementById('info-banner').innerHTML = - `🔍 Supports Swagger 2.0 & OpenAPI 3.x | Current version: ${version}`; }, onFailure: function(error) { console.error('Loading failed:', error); @@ -155,4 +142,4 @@

⚠️ Please provide an API documentation URL

}; - \ No newline at end of file + From e20a42138372840d20d247ce398a8dc93a106ee9 Mon Sep 17 00:00:00 2001 From: min0625 <70873102+min0625@users.noreply.github.com> Date: Wed, 5 Nov 2025 02:45:41 +0800 Subject: [PATCH 2/2] feat: upgrade to Swagger UI 5.30.2 and unify URL parameter - Upgrade Swagger UI from 5.10.0 to 5.30.2 to fix OpenAPI 3.x rendering issues - Unify parameter name from 'uri' to 'url' for consistency - Remove CORS proxy functionality (direct loading only) - Remove all test HTML files (compare.html, index-new.html, index-simple.html, test.html, test-latest.html) - Add loading indicator for better UX - Update documentation (README.md & README.zh-TW.md) to reflect changes - Fix GitHub Raw URL format in examples --- README.md | 43 ++++++++++++++++++--------- README.zh-TW.md | 47 ++++++++++++++++++++---------- index.html | 77 +++++++++++++++++++++++++------------------------ 3 files changed, 100 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 47c5810..915617b 100644 --- a/README.md +++ b/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,10 +22,10 @@ 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 @@ -33,33 +33,33 @@ https://min0625.github.io/openapi-viewer?uri=https://petstore3.swagger.io/api/v3 Use GitHub Raw URL: ``` -https://min0625.github.io/openapi-viewer?uri=https://raw.githubusercontent.com/min0625/openapi-viewer/refs/heads/main/swagger.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 +- **Swagger UI**: v5.30.2 - **Supported Formats**: - Swagger 2.0 (JSON/YAML) - OpenAPI 3.0.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//// + ``` + +2. **Use GitHub Gist**: Great for sharing example documentation + ``` + https://gist.githubusercontent.com///raw/ + ``` + +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: diff --git a/README.zh-TW.md b/README.zh-TW.md index 1bffd46..11a11d5 100644 --- a/README.zh-TW.md +++ b/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,44 +22,44 @@ ### 方式 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/min0625/openapi-viewer/refs/heads/main/swagger.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) @@ -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//// + ``` + +2. **使用 GitHub Gist**: 適合分享範例文件 + ``` + https://gist.githubusercontent.com///raw/ + ``` + +3. **配置伺服器 CORS**: 如果你控制 API 伺服器，添加以下 headers: + ``` + Access-Control-Allow-Origin: * + Access-Control-Allow-Methods: GET, OPTIONS + ``` ### GitHub Raw URL 格式 -使用 GitHub 檔案時,使用以下格式: +使用 GitHub 檔案時，使用以下格式： ``` https://raw.githubusercontent.com//// ``` diff --git a/index.html b/index.html index 59ae224..9146bdd 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ OpenAPI Viewer - +