fix: 修复无法直接通过后端地址访问API文档的问题 (#20)

Author: insistence

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秘钥

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秘钥

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秘钥

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秘钥

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):

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:    <cyan>http://{local_ip}:{port}</cyan>']
+    app_links.extend(f'📡 Network:  <cyan>http://{ip}:{port}</cyan>' 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:    <cyan>http://{local_ip}:{port}{APIDocsUtil.docs_url()}</cyan>']
+        swagger_links.extend(
+            f'📡 Network:  <cyan>http://{ip}:{port}{APIDocsUtil.docs_url()}</cyan>' 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:    <cyan>http://{local_ip}:{port}{APIDocsUtil.redoc_url()}</cyan>']
+        redoc_links.extend(
+            f'📡 Network:  <cyan>http://{ip}:{port}{APIDocsUtil.redoc_url()}</cyan>' 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)
     # 加载中间件处理方法