Swagger與Spring Boot的版本不匹配是常見誘因，可能導致配置失敗或功能異常。需嚴格遵循官方推薦的版本組合（如Spring Boot 2.7.x適配Swagger 3.0.x，Spring Boot 3.x適配Swagger 4.x及以上），避免跨大版本使用?？赏ㄟ^pom.xml（Maven）或build.gradle（Gradle）檢查并調整依賴版本，確保兩者兼容。
使用Docker將Swagger UI或Editor容器化，可徹底規避CentOS與其他系統的環境差異（如Node.js版本、依賴庫沖突）。例如，通過官方鏡像快速部署Swagger UI：
docker run -d -p 80:8080 --name swagger-ui swaggerapi/swagger-ui
此方式確保無論宿主機是CentOS、Windows還是macOS，均能獲得一致的運行環境。
Swagger UI的版本需與API規范版本嚴格對應：
OpenAPI 3.0+規范的JSON/YAML文檔；Swagger 2.0規范。swagger-cli工具轉換）。新版Swagger工具（如Swagger UI 3.x、Swagger Editor）要求Node.js 12及以上版本，而舊版CentOS可能默認安裝Node.js 8或10?？赏ㄟ^nvm（Node Version Manager）安裝指定版本：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
source ~/.bashrc
nvm install 14 # 安裝Node.js 14
nvm use 14 # 切換至該版本
確保Swagger工具運行在支持的Node.js環境中。
CentOS默認防火墻（firewalld）可能阻止Swagger UI的端口訪問（如8080、3000）。需開放對應端口并重載防火墻：
sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
sudo firewall-cmd --reload
若使用ufw（Ubuntu風格防火墻），可執行sudo ufw allow 8080。同時，確保Spring Boot應用配置了springfox.documentation.swagger.v2.host=0.0.0.0，允許所有IP訪問API文檔。
若Swagger UI無法正常加載頁面，需檢查Spring Boot項目的靜態資源配置（如移除@EnableSwaggerWebMvc注解，實現WebMvcConfigurer接口并添加靜態資源映射），確保/swagger-ui/**路徑可訪問。此外，確認Swagger UI目錄的權限（如chmod -R 755 /opt/swagger），避免因權限不足導致文件無法讀取。
項目中的依賴沖突（如Guava、Jackson版本不兼容）可能導致Swagger功能異常?？墒褂肕aven Helper插件（IntelliJ IDEA）分析依賴樹，排除沖突的傳遞依賴。例如，若minio依賴引入了不兼容的Guava版本，可在pom.xml中排除：
<dependency>
<groupId>io.minio</groupId>
<artifactId>minio</artifactId>
<exclusions>
<exclusion>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
</exclusion>
</exclusions>
</dependency>
隨后執行mvn clean install重新構建項目。
若問題仍未解決，需查看Swagger UI瀏覽器的控制臺錯誤（F12打開）和服務端的應用日志（如Spring Boot的logs/application.log），定位具體錯誤原因（如404錯誤可能為路徑配置錯誤，500錯誤可能為依賴沖突）。結合錯誤信息進一步調整配置。
