From 2bbba486d96e27c3aaea89bf0fd606e331357225 Mon Sep 17 00:00:00 2001 From: insistence <3055204202@qq.com> Date: Sat, 31 Jan 2026 19:42:46 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=E6=97=A0=E6=B3=95?= =?UTF-8?q?=E7=9B=B4=E6=8E=A5=E9=80=9A=E8=BF=87=E5=90=8E=E7=AB=AF=E5=9C=B0?= =?UTF-8?q?=E5=9D=80=E8=AE=BF=E9=97=AEAPI=E6=96=87=E6=A1=A3=E7=9A=84?= =?UTF-8?q?=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ruoyi-fastapi-backend/.env.dev | 4 + ruoyi-fastapi-backend/.env.dockermy | 4 + ruoyi-fastapi-backend/.env.dockerpg | 4 + ruoyi-fastapi-backend/.env.prod | 4 + ruoyi-fastapi-backend/config/env.py | 2 + ruoyi-fastapi-backend/server.py | 77 ++-- ruoyi-fastapi-backend/utils/server_util.py | 399 ++++++++++++++++++ .../src/views/tool/swagger/index.vue | 2 +- 8 files changed, 453 insertions(+), 43 deletions(-) create mode 100644 ruoyi-fastapi-backend/utils/server_util.py diff --git a/ruoyi-fastapi-backend/.env.dev b/ruoyi-fastapi-backend/.env.dev index c0735a7..0048481 100644 --- a/ruoyi-fastapi-backend/.env.dev +++ b/ruoyi-fastapi-backend/.env.dev @@ -17,6 +17,10 @@ APP_RELOAD = true APP_IP_LOCATION_QUERY = true # 应用是否允许账号同时登录 APP_SAME_TIME_LOGIN = true +# 应用是否禁用Swagger文档 +APP_DISABLE_SWAGGER = false +# 应用是否禁用ReDoc文档 +APP_DISABLE_REDOC = false # -------- Jwt配置 -------- # Jwt秘钥 diff --git a/ruoyi-fastapi-backend/.env.dockermy b/ruoyi-fastapi-backend/.env.dockermy index 6963cd2..7c0796e 100644 --- a/ruoyi-fastapi-backend/.env.dockermy +++ b/ruoyi-fastapi-backend/.env.dockermy @@ -17,6 +17,10 @@ APP_RELOAD = false APP_IP_LOCATION_QUERY = true # 应用是否允许账号同时登录 APP_SAME_TIME_LOGIN = true +# 应用是否禁用Swagger文档 +APP_DISABLE_SWAGGER = true +# 应用是否禁用ReDoc文档 +APP_DISABLE_REDOC = true # -------- Jwt配置 -------- # Jwt秘钥 diff --git a/ruoyi-fastapi-backend/.env.dockerpg b/ruoyi-fastapi-backend/.env.dockerpg index ccaeb53..e254e15 100644 --- a/ruoyi-fastapi-backend/.env.dockerpg +++ b/ruoyi-fastapi-backend/.env.dockerpg @@ -17,6 +17,10 @@ APP_RELOAD = false APP_IP_LOCATION_QUERY = true # 应用是否允许账号同时登录 APP_SAME_TIME_LOGIN = true +# 应用是否禁用Swagger文档 +APP_DISABLE_SWAGGER = true +# 应用是否禁用ReDoc文档 +APP_DISABLE_REDOC = true # -------- Jwt配置 -------- # Jwt秘钥 diff --git a/ruoyi-fastapi-backend/.env.prod b/ruoyi-fastapi-backend/.env.prod index 8ed5d3c..5237abc 100644 --- a/ruoyi-fastapi-backend/.env.prod +++ b/ruoyi-fastapi-backend/.env.prod @@ -17,6 +17,10 @@ APP_RELOAD = false APP_IP_LOCATION_QUERY = true # 应用是否允许账号同时登录 APP_SAME_TIME_LOGIN = true +# 应用是否禁用Swagger文档 +APP_DISABLE_SWAGGER = true +# 应用是否禁用ReDoc文档 +APP_DISABLE_REDOC = true # -------- Jwt配置 -------- # Jwt秘钥 diff --git a/ruoyi-fastapi-backend/config/env.py b/ruoyi-fastapi-backend/config/env.py index 153b7a1..518c068 100644 --- a/ruoyi-fastapi-backend/config/env.py +++ b/ruoyi-fastapi-backend/config/env.py @@ -23,6 +23,8 @@ class AppSettings(BaseSettings): app_reload: bool = True app_ip_location_query: bool = True app_same_time_login: bool = True + app_disable_swagger: bool = False + app_disable_redoc: bool = False class JwtSettings(BaseSettings): diff --git a/ruoyi-fastapi-backend/server.py b/ruoyi-fastapi-backend/server.py index 724d8b5..42bc4bd 100644 --- a/ruoyi-fastapi-backend/server.py +++ b/ruoyi-fastapi-backend/server.py @@ -1,9 +1,7 @@ from collections.abc import AsyncGenerator from contextlib import asynccontextmanager -from fastapi import FastAPI, applications -from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html -from fastapi.responses import HTMLResponse +from fastapi import FastAPI from common.router import auto_register_routers from config.env import AppConfig @@ -15,6 +13,7 @@ from sub_applications.handle import handle_sub_applications from utils.common_util import worship from utils.log_util import logger +from utils.server_util import APIDocsUtil, IPUtil # 生命周期事件 @@ -28,48 +27,35 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]: await RedisUtil.init_sys_config(app.state.redis) await SchedulerUtil.init_system_scheduler() logger.info(f'🚀 {AppConfig.app_name}启动成功') - yield - await RedisUtil.close_redis_pool(app) - await SchedulerUtil.close_system_scheduler() - - -def setup_docs_static_resources( - redoc_js_url: str = 'https://registry.npmmirror.com/redoc/2/files/bundles/redoc.standalone.js', - redoc_favicon_url: str = 'https://fastapi.tiangolo.com/img/favicon.png', - swagger_js_url: str = 'https://registry.npmmirror.com/swagger-ui-dist/5/files/swagger-ui-bundle.js', - swagger_css_url: str = 'https://registry.npmmirror.com/swagger-ui-dist/5/files/swagger-ui.css', - swagger_favicon_url: str = 'https://fastapi.tiangolo.com/img/favicon.png', -) -> None: - """ - 配置文档静态资源 + host = AppConfig.app_host + port = AppConfig.app_port + if host == '0.0.0.0': + local_ip = IPUtil.get_local_ip() + network_ips = IPUtil.get_network_ips() + else: + local_ip = host + network_ips = [host] - :param redoc_js_url: 用于加载ReDoc JavaScript的URL - :param redoc_favicon_url: ReDoc要使用的favicon的URL - :param swagger_js_url: 用于加载Swagger UI JavaScript的URL - :param swagger_css_url: 用于加载Swagger UI CSS的URL - :param swagger_favicon_url: Swagger UI要使用的favicon的URL - :return: - """ + app_links = [f'🏠 Local: http://{local_ip}:{port}'] + app_links.extend(f'📡 Network: http://{ip}:{port}' for ip in network_ips) + logger.opt(colors=True).info('💻 应用地址:\n' + '\n'.join(app_links)) - def redoc_monkey_patch(*args, **kwargs) -> HTMLResponse: - return get_redoc_html( - *args, - **kwargs, - redoc_js_url=redoc_js_url, - redoc_favicon_url=redoc_favicon_url, + if not AppConfig.app_disable_swagger: + swagger_links = [f'🏠 Local: http://{local_ip}:{port}{APIDocsUtil.docs_url()}'] + swagger_links.extend( + f'📡 Network: http://{ip}:{port}{APIDocsUtil.docs_url()}' for ip in network_ips ) + logger.opt(colors=True).info('📄 Swagger文档:\n' + '\n'.join(swagger_links)) - def swagger_ui_monkey_patch(*args, **kwargs) -> HTMLResponse: - return get_swagger_ui_html( - *args, - **kwargs, - swagger_js_url=swagger_js_url, - swagger_css_url=swagger_css_url, - swagger_favicon_url=swagger_favicon_url, + if not AppConfig.app_disable_redoc: + redoc_links = [f'🏠 Local: http://{local_ip}:{port}{APIDocsUtil.redoc_url()}'] + redoc_links.extend( + f'📡 Network: http://{ip}:{port}{APIDocsUtil.redoc_url()}' for ip in network_ips ) - - applications.get_redoc_html = redoc_monkey_patch - applications.get_swagger_ui_html = swagger_ui_monkey_patch + logger.opt(colors=True).info('📚 ReDoc文档:\n' + '\n'.join(redoc_links)) + yield + await RedisUtil.close_redis_pool(app) + await SchedulerUtil.close_system_scheduler() def create_app() -> FastAPI: @@ -78,16 +64,23 @@ def create_app() -> FastAPI: :return: FastAPI对象 """ - # 配置文档静态资源 - setup_docs_static_resources() + # 配置API文档静态资源 + APIDocsUtil.setup_docs_static_resources() # 初始化FastAPI对象 app = FastAPI( title=AppConfig.app_name, description=f'{AppConfig.app_name}接口文档', version=AppConfig.app_version, lifespan=lifespan, + openapi_url=APIDocsUtil.proxy_openapi_url(), + docs_url=APIDocsUtil.proxy_docs_url(), + redoc_url=APIDocsUtil.proxy_redoc_url(), + swagger_ui_oauth2_redirect_url=APIDocsUtil.proxy_oauth2_redirect_url(), ) + # 自定义API文档路由，修复无法直接通过后端地址访问文档的问题 + APIDocsUtil.custom_api_docs_router(app) + # 挂载子应用 handle_sub_applications(app) # 加载中间件处理方法 diff --git a/ruoyi-fastapi-backend/utils/server_util.py b/ruoyi-fastapi-backend/utils/server_util.py new file mode 100644 index 0000000..873fe89 --- /dev/null +++ b/ruoyi-fastapi-backend/utils/server_util.py @@ -0,0 +1,399 @@ +import ipaddress +import socket +from collections.abc import Callable + +import psutil +from fastapi import FastAPI, Request, applications +from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html +from fastapi.openapi.utils import get_openapi +from fastapi.responses import HTMLResponse, JSONResponse + +from config.env import AppConfig + + +class APIDocsUtil: + """ + API文档工具类 + """ + + # API文档URLs + _OPENAPI_URL = '/openapi.json' + _PROXY_OPENAPI_URL = '/proxy-openapi.json' + _DOCS_URL = '/docs' + _PROXY_DOCS_URL = '/proxy-docs' + _REDOC_URL = '/redoc' + _PROXY_REDOC_URL = '/proxy-redoc' + _OAUTH2_REDIRECT_URL = '/docs/oauth2-redirect' + _PROXY_OAUTH2_REDIRECT_URL = '/proxy-docs/oauth2-redirect' + + # 文档静态资源URLs + DEFAULT_REDOC_JS_URL = 'https://registry.npmmirror.com/redoc/2/files/bundles/redoc.standalone.js' + DEFAULT_REDOC_FAVICON_URL = 'https://fastapi.tiangolo.com/img/favicon.png' + DEFAULT_SWAGGER_JS_URL = 'https://registry.npmmirror.com/swagger-ui-dist/5/files/swagger-ui-bundle.js' + DEFAULT_SWAGGER_CSS_URL = 'https://registry.npmmirror.com/swagger-ui-dist/5/files/swagger-ui.css' + DEFAULT_SWAGGER_FAVICON_URL = 'https://fastapi.tiangolo.com/img/favicon.png' + + @classmethod + def proxy_openapi_url(cls) -> str: + """ + 代理OpenAPI文档URL + """ + return cls._PROXY_OPENAPI_URL if not AppConfig.app_disable_swagger and not AppConfig.app_disable_redoc else None + + @classmethod + def docs_url(cls) -> str: + """ + 文档URL + """ + return cls._DOCS_URL + + @classmethod + def proxy_docs_url(cls) -> str: + """ + 代理文档URL + """ + return cls._PROXY_DOCS_URL if not AppConfig.app_disable_swagger else None + + @classmethod + def redoc_url(cls) -> str: + """ + ReDoc文档URL + """ + return cls._REDOC_URL + + @classmethod + def proxy_redoc_url(cls) -> str: + """ + 代理ReDoc文档URL + """ + return cls._PROXY_REDOC_URL if not AppConfig.app_disable_redoc else None + + @classmethod + def proxy_oauth2_redirect_url(cls) -> str: + """ + 代理OAuth2重定向URL + """ + return cls._PROXY_OAUTH2_REDIRECT_URL if not AppConfig.app_disable_swagger else None + + @classmethod + def setup_docs_static_resources( + cls, + redoc_js_url: str = DEFAULT_REDOC_JS_URL, + redoc_favicon_url: str = DEFAULT_REDOC_FAVICON_URL, + swagger_js_url: str = DEFAULT_SWAGGER_JS_URL, + swagger_css_url: str = DEFAULT_SWAGGER_CSS_URL, + swagger_favicon_url: str = DEFAULT_SWAGGER_FAVICON_URL, + ) -> None: + """ + 配置文档静态资源 + + :param redoc_js_url: 用于加载ReDoc JavaScript的URL + :param redoc_favicon_url: ReDoc要使用的favicon的URL + :param swagger_js_url: 用于加载Swagger UI JavaScript的URL + :param swagger_css_url: 用于加载Swagger UI CSS的URL + :param swagger_favicon_url: Swagger UI要使用的favicon的URL + :return: + """ + + def redoc_monkey_patch(*args, **kwargs) -> HTMLResponse: + return get_redoc_html( + *args, + **kwargs, + redoc_js_url=redoc_js_url, + redoc_favicon_url=redoc_favicon_url, + ) + + def swagger_ui_monkey_patch(*args, **kwargs) -> HTMLResponse: + return get_swagger_ui_html( + *args, + **kwargs, + swagger_js_url=swagger_js_url, + swagger_css_url=swagger_css_url, + swagger_favicon_url=swagger_favicon_url, + ) + + applications.get_redoc_html = redoc_monkey_patch + applications.get_swagger_ui_html = swagger_ui_monkey_patch + + @classmethod + def custom_api_docs_router( + cls, + app: FastAPI, + redoc_js_url: str = DEFAULT_REDOC_JS_URL, + redoc_favicon_url: str = DEFAULT_REDOC_FAVICON_URL, + swagger_js_url: str = DEFAULT_SWAGGER_JS_URL, + swagger_css_url: str = DEFAULT_SWAGGER_CSS_URL, + swagger_favicon_url: str = DEFAULT_SWAGGER_FAVICON_URL, + ) -> None: + """ + 自定义API文档路由 + + :param app: FastAPI对象 + :param redoc_js_url: 用于加载ReDoc JavaScript的URL + :param redoc_favicon_url: ReDoc要使用的favicon的URL + :param swagger_js_url: 用于加载Swagger UI JavaScript的URL + :param swagger_css_url: 用于加载Swagger UI CSS的URL + :param swagger_favicon_url: Swagger UI要使用的favicon的URL + :return: + """ + + async def custom_openapi(request: Request) -> JSONResponse: + return await cls._custom_openapi(app) + + async def custom_redoc(request: Request) -> HTMLResponse: + return await cls._custom_redoc(app, redoc_js_url, redoc_favicon_url) + + async def custom_swagger(request: Request) -> HTMLResponse: + return await cls._custom_swagger(app, swagger_js_url, swagger_css_url, swagger_favicon_url) + + async def custom_swagger_ui_redirect(request: Request) -> HTMLResponse: + return await cls._custom_swagger_ui_redirect(app, swagger_favicon_url) + + # 注册路由 + app.add_route(cls._OPENAPI_URL, custom_openapi, include_in_schema=False) + cls._register_docs_routes(app, custom_swagger, custom_swagger_ui_redirect, custom_redoc) + + @classmethod + async def _custom_openapi(cls, app: FastAPI) -> JSONResponse: + """ + 自定义 OpenAPI 路由处理函数 + + :param app: FastAPI对象 + :return: openapi的json响应 + """ + openapi_schema = get_openapi( + title=app.title, + version=app.version, + openapi_version=app.openapi_version, + summary=app.summary, + description=app.description, + terms_of_service=app.terms_of_service, + contact=app.contact, + license_info=app.license_info, + routes=app.routes, + webhooks=app.webhooks.routes, + tags=app.openapi_tags, + separate_input_output_schemas=app.separate_input_output_schemas, + external_docs=app.openapi_external_docs, + ) + return JSONResponse(openapi_schema) + + @classmethod + async def _custom_redoc( + cls, + app: FastAPI, + redoc_js_url: str, + redoc_favicon_url: str, + ) -> HTMLResponse: + """ + 自定义 ReDoc 路由处理函数 + + :param app: FastAPI对象 + :param redoc_js_url: 用于加载ReDoc JavaScript的URL + :param redoc_favicon_url: ReDoc要使用的favicon的URL + :return: ReDoc HTML响应 + """ + if not AppConfig.app_disable_redoc: + return get_redoc_html( + openapi_url=cls._OPENAPI_URL, + title=f'{app.title} - ReDoc', + redoc_js_url=redoc_js_url, + redoc_favicon_url=redoc_favicon_url, + ) + return cls._get_disabled_html_content( + f'{app.title} - ReDoc', + 'ReDoc', + redoc_favicon_url, + ) + + @classmethod + async def _custom_swagger( + cls, + app: FastAPI, + swagger_js_url: str, + swagger_css_url: str, + swagger_favicon_url: str, + ) -> HTMLResponse: + """ + 自定义 Swagger UI 路由处理函数 + + :param app: FastAPI对象 + :param swagger_js_url: 用于加载Swagger UI JavaScript的URL + :param swagger_css_url: 用于加载Swagger UI CSS的URL + :param swagger_favicon_url: Swagger UI要使用的favicon的URL + :return: Swagger UI HTML响应 + """ + if not AppConfig.app_disable_swagger: + return get_swagger_ui_html( + openapi_url=cls._OPENAPI_URL, + title=f'{app.title} - Swagger UI', + swagger_js_url=swagger_js_url, + swagger_css_url=swagger_css_url, + swagger_favicon_url=swagger_favicon_url, + oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url, + init_oauth=app.swagger_ui_init_oauth, + swagger_ui_parameters=app.swagger_ui_parameters, + ) + return cls._get_disabled_html_content( + f'{app.title} - Swagger UI', + 'Swagger UI', + swagger_favicon_url, + ) + + @classmethod + async def _custom_swagger_ui_redirect( + cls, + app: FastAPI, + swagger_favicon_url: str, + ) -> HTMLResponse: + """ + 自定义 Swagger UI OAuth2 重定向路由处理函数 + + :param app: FastAPI对象 + :param swagger_favicon_url: Swagger UI要使用的favicon的URL + :return: Swagger UI OAuth2重定向HTML响应 + """ + if not AppConfig.app_disable_swagger: + return get_swagger_ui_oauth2_redirect_html() + return cls._get_disabled_html_content( + f'{app.title} - Swagger UI OAuth2 Redirect', + 'Swagger UI OAuth2 Redirect', + swagger_favicon_url, + ) + + @staticmethod + def _get_disabled_html_content(title: str, name: str, favicon_url: str) -> HTMLResponse: + """ + 生成禁用文档的HTML内容 + + :param title: 页面标题 + :param name: 文档名称 + :param favicon_url: 图标地址 + :return: 禁用文档HTML响应 + """ + html = f""" + + + + {title} + + + + + + + + + +

{name} has been disabled. Please enable it first.

+ + + """ + return HTMLResponse(html) + + @classmethod + def _register_docs_routes( + cls, app: FastAPI, swagger_handler: Callable, redirect_handler: Callable, redoc_handler: Callable + ) -> None: + """ + 注册文档路由 + + :param app: FastAPI对象 + :param swagger_handler: Swagger UI 路由处理函数 + :param redirect_handler: Swagger UI OAuth2 重定向路由处理函数 + :param redoc_handler: ReDoc 路由处理函数 + :return: + """ + swagger_urls: list[str] = ( + [cls._DOCS_URL] if not AppConfig.app_disable_swagger else [cls._DOCS_URL, cls._PROXY_DOCS_URL] + ) + swagger_redirect_urls: list[str] = ( + [cls._OAUTH2_REDIRECT_URL] + if not AppConfig.app_disable_swagger + else [cls._OAUTH2_REDIRECT_URL, cls._PROXY_OAUTH2_REDIRECT_URL] + ) + redoc_urls: list[str] = ( + [cls._REDOC_URL] if not AppConfig.app_disable_redoc else [cls._REDOC_URL, cls._PROXY_REDOC_URL] + ) + + for url in swagger_urls: + app.add_route(url, swagger_handler, include_in_schema=False) + for url in swagger_redirect_urls: + app.add_route(url, redirect_handler, include_in_schema=False) + for url in redoc_urls: + app.add_route(url, redoc_handler, include_in_schema=False) + + +class IPUtil: + """ + IP工具类 + """ + + @classmethod + def get_local_ip(cls) -> str: + """ + 获取本机Local IP + """ + try: + for snics in psutil.net_if_addrs().values(): + for snic in snics: + if snic.family == socket.AF_INET and snic.address.startswith('127.'): + return snic.address + except Exception: + pass + + return '127.0.0.1' + + @classmethod + def get_network_ips(cls) -> list[str]: + """ + 获取本机Network IP列表 + """ + network_ips = [] + try: + # 获取网卡状态 + stats = psutil.net_if_stats() + for name, snics in psutil.net_if_addrs().items(): + # 过滤掉状态为DOWN的网卡 + if name in stats and not stats[name].isup: + continue + + for snic in snics: + if snic.family == socket.AF_INET: + try: + ip_obj = ipaddress.ip_address(snic.address) + if ip_obj.is_loopback or ip_obj.is_link_local: + continue + network_ips.append(snic.address) + except ValueError: + continue + except Exception: + pass + + # 优先显示首选出站IP + preferred_ip = None + try: + with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s: + s.connect(('8.8.8.8', 80)) + preferred_ip = s.getsockname()[0] + except Exception: + pass + + if preferred_ip: + if preferred_ip in network_ips: + network_ips.remove(preferred_ip) + network_ips.insert(0, preferred_ip) + + if not network_ips: + network_ips = ['127.0.0.1'] + + return network_ips diff --git a/ruoyi-fastapi-frontend/src/views/tool/swagger/index.vue b/ruoyi-fastapi-frontend/src/views/tool/swagger/index.vue index fc94340..6b29a98 100644 --- a/ruoyi-fastapi-frontend/src/views/tool/swagger/index.vue +++ b/ruoyi-fastapi-frontend/src/views/tool/swagger/index.vue @@ -8,7 +8,7 @@ export default { components: { iFrame }, data() { return { - url: process.env.VUE_APP_BASE_API + "/docs" + url: process.env.VUE_APP_BASE_API + "/proxy-docs" }; }, };