swagger ui离线安装

### 在离线环境中安装和配置 Swagger UI 在没有互联网连接的环境下，安装和配置 **Swagger UI** 主要涉及手动下载静态资源并将其集成到后端服务中。以下是具体步骤： 1. **下载 Swagger UI 静态文件** 由于无法直接从网络上获取资源，需要提前在有网络的环境中下载 Swagger UI 的静态资源包。可以从 [Swagger UI 官方 GitHub 页面](https://github.com/swagger-api/swagger-ui) 获取最新版本的源码或者打包好的静态资源。将这些文件复制到目标机器上的项目目录中，例如 `./static/swagger-ui/`。 2. **集成到 FastAPI（或其他 Web 框架）** 如果使用的是 **FastAPI**，可以通过自定义路由来加载本地存储的 Swagger UI 资源。首先确保项目结构中有存放静态文件的目录，并在代码中指定该路径作为文档界面的根目录。 ```python from fastapi import FastAPI from fastapi.staticfiles import StaticFiles from fastapi.openapi.docs import get_swagger_ui_html app = FastAPI(docs_url=None) # 禁用默认的文档生成 # 挂载本地 Swagger UI 静态资源 app.mount("/static", StaticFiles(directory="path/to/local/static/files"), name="static") @app.get("/docs", include_in_schema=False) async def custom_swagger_ui(): return get_swagger_ui_html( openapi_url="/openapi.json", title="API Docs", swagger_js_url="/static/swagger-ui-bundle.js", swagger_css_url="/static/swagger-ui.css" ) ``` 3. **验证部署** 启动服务后访问 `/docs` 路径，如果成功显示 Swagger UI 界面，则表示部署成功。检查浏览器控制台是否有任何错误信息以排除潜在问题，如资源路径不正确或依赖项缺失等。 4. **处理 OpenAPI 规范文件** 确保服务能够提供一个有效的 `openapi.json` 或 `openapi.yaml` 文件供 Swagger UI 加载。对于 FastAPI，默认情况下会自动暴露 `/openapi.json` 接口，无需额外开发工作即可支持此功能。 5. **备用方案：调试工具获取资源** 如果之前已经在在线环境中使用过 Swagger UI，可以利用浏览器开发者工具（Network 面板）捕获实际请求的资源 URL，然后手动下载这些文件并导入到离线环境中的相应位置[^2]。 ### 示例代码：FastAPI 自定义 Swagger UI 资源路径 ```python from fastapi import FastAPI from fastapi.staticfiles import StaticFiles from fastapi.openapi.docs import get_swagger_ui_html app = FastAPI(docs_url=None) # 假设 static 目录下包含了所有必要的 swagger-ui 文件 app.mount("/static", StaticFiles(directory="static"), name="static") @app.get("/docs", include_in_schema=False) async def custom_docs(): return get_swagger_ui_html( openapi_url="/openapi.json", title="Custom API Docs", swagger_js_url="/static/swagger-ui-bundle.js", swagger_css_url="/static/swagger-ui.css" ) @app.get("/openapi.json", include_in_schema=False) async def get_open_api_endpoint(): return app.openapi() ``` ### 注意事项 - **跨域问题**：如果 Swagger UI 和 API 服务不在同一个域名下，请确保设置了正确的 CORS 策略。 - **缓存清除**：更新了 Swagger UI 的静态资源后，可能需要清除浏览器缓存才能看到最新的界面效果。 - **安全性考虑**：生产环境中建议对文档接口进行适当的安全限制，避免不必要的信息泄露风险。 ---