[Feature] Add offline FastAPI documentation support for air-gapped environments (#30184)

Signed-off-by: rickychen-infinirc <ricky.chen@infinirc.com>
Signed-off-by: RickyChen / 陳昭儒 <ricky.chen@infinirc.com>
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Co-authored-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>

pyproject.toml

@@ -120,7 +120,7 @@ python = "./.venv"
 # these files may be written in non english words
 extend-exclude = ["tests/models/fixtures/*", "tests/prompts/*",
     "benchmarks/sonnet.txt", "tests/lora/data/*", "build/*",
-    "vllm/third_party/*"]
+    "vllm/third_party/*", "vllm/entrypoints/serve/instrumentator/static/*"]
 ignore-hidden = true
 ignore-files = true
 ignore-dot = true
@@ -302,4 +302,4 @@ windo = "windo"
 [tool.typos.type.vimscript.extend-words]
 
 [tool.uv]
-no-build-isolation-package = ["torch"]
+no-build-isolation-package = ["torch"]

setup.py

@@ -863,6 +863,8 @@ package_data = {
         "py.typed",
         "model_executor/layers/fused_moe/configs/*.json",
         "model_executor/layers/quantization/utils/configs/*.json",
+        "entrypoints/serve/instrumentator/static/*.js",
+        "entrypoints/serve/instrumentator/static/*.css",
     ]
 }
 

vllm/entrypoints/openai/api_server.py

@@ -870,6 +870,8 @@ def build_app(args: Namespace) -> FastAPI:
         app = FastAPI(
             openapi_url=None, docs_url=None, redoc_url=None, lifespan=lifespan
         )
+    elif args.enable_offline_docs:
+        app = FastAPI(docs_url=None, redoc_url=None, lifespan=lifespan)
     else:
         app = FastAPI(lifespan=lifespan)
     app.state.args = args

vllm/entrypoints/openai/cli_args.py

@@ -194,6 +194,11 @@ class FrontendArgs:
     If set to True, only enable the Tokens In<>Out endpoint. 
     This is intended for use in a Disaggregated Everything setup.
     """
+    enable_offline_docs: bool = False
+    """
+    Enable offline FastAPI documentation for air-gapped environments.
+    Uses vendored static assets bundled with vLLM.
+    """
 
     @staticmethod
     def add_cli_args(parser: FlexibleArgumentParser) -> FlexibleArgumentParser:

vllm/entrypoints/serve/__init__.py

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
-
 from fastapi import FastAPI
 
 import vllm.envs as envs
@@ -22,6 +21,7 @@ def register_vllm_serve_api_routers(app: FastAPI):
     )
 
     attach_lora_router(app)
+
     from vllm.entrypoints.serve.elastic_ep.api_router import (
         attach_router as attach_elastic_ep_router,
     )
@@ -82,6 +82,11 @@ def register_vllm_serve_api_routers(app: FastAPI):
 
     attach_health_router(app)
 
+    from vllm.entrypoints.serve.instrumentator.offline_docs import (
+        attach_router as attach_offline_docs_router,
+    )
+
+    attach_offline_docs_router(app)
     from vllm.entrypoints.serve.instrumentator.server_info import (
         attach_router as attach_server_info_router,
     )

vllm/entrypoints/serve/instrumentator/offline_docs.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Offline FastAPI documentation support for air-gapped environments."""
+
+import pathlib
+
+from fastapi import FastAPI
+from fastapi.openapi.docs import (
+    get_swagger_ui_html,
+    get_swagger_ui_oauth2_redirect_html,
+)
+from fastapi.staticfiles import StaticFiles
+
+from vllm.logger import init_logger
+
+logger = init_logger(__name__)
+
+
+def attach_router(app: FastAPI) -> None:
+    """Attach offline docs router if enabled via args."""
+    args = getattr(app.state, "args", None)
+    if args is None or not getattr(args, "enable_offline_docs", False):
+        return
+
+    static_dir = pathlib.Path(__file__).parent / "static"
+
+    if not static_dir.exists():
+        logger.warning(
+            "Static directory not found at %s. Offline docs will not be available.",
+            static_dir,
+        )
+        return
+
+    app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+    @app.get("/docs", include_in_schema=False)
+    async def custom_swagger_ui_html():
+        return get_swagger_ui_html(
+            openapi_url=app.openapi_url,
+            title=app.title + " - Swagger UI",
+            oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
+            swagger_js_url="/static/swagger-ui-bundle.js",
+            swagger_css_url="/static/swagger-ui.css",
+        )
+
+    @app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
+    async def swagger_ui_redirect():
+        return get_swagger_ui_oauth2_redirect_html()
+
+    logger.info("Offline documentation enabled with vendored static assets")