✨ Add relative docs everywhere (#12421)

fastapi/applications.py

@@ -27,7 +27,7 @@ from fastapi.openapi.docs import (
     get_swagger_ui_html,
     get_swagger_ui_oauth2_redirect_html,
 )
-from fastapi.openapi.utils import get_openapi
+from fastapi.openapi.utils import calculate_relative_url, get_openapi
 from fastapi.params import Depends
 from fastapi.types import DecoratedCallable, IncEx
 from fastapi.utils import generate_unique_id
@@ -679,6 +679,7 @@ class FastAPI(Starlette):
                 """
             ),
         ] = True,
+        relative_docs: bool = False,
         responses: Annotated[
             Optional[Dict[Union[int, str], Dict[str, Any]]],
             Doc(
@@ -831,6 +832,7 @@ class FastAPI(Starlette):
         self.openapi_url = openapi_url
         self.openapi_tags = openapi_tags
         self.root_path_in_servers = root_path_in_servers
+        self.relative_docs = relative_docs
         self.docs_url = docs_url
         self.redoc_url = redoc_url
         self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url
@@ -1006,6 +1008,10 @@ class FastAPI(Starlette):
                     if root_path and self.root_path_in_servers:
                         self.servers.insert(0, {"url": root_path})
                         server_urls.add(root_path)
+                if self.relative_docs and self.docs_url:
+                    relative_server = "../" * self.docs_url.count("/")
+                    self.servers.insert(0, {"url": relative_server})
+                    server_urls.add(relative_server)
                 return JSONResponse(self.openapi())
 
             self.add_route(self.openapi_url, openapi, include_in_schema=False)
@@ -1013,6 +1019,11 @@ class FastAPI(Starlette):
 
             async def swagger_ui_html(req: Request) -> HTMLResponse:
                 root_path = req.scope.get("root_path", "").rstrip("/")
+                if self.relative_docs and self.docs_url:
+                    openapi_url = calculate_relative_url(
+                        self.docs_url, self.openapi_url
+                    )
+                else:
                     openapi_url = root_path + self.openapi_url
                 oauth2_redirect_url = self.swagger_ui_oauth2_redirect_url
                 if oauth2_redirect_url:
@@ -1040,6 +1051,11 @@ class FastAPI(Starlette):
         if self.openapi_url and self.redoc_url:
 
             async def redoc_html(req: Request) -> HTMLResponse:
+                if self.relative_docs and self.redoc_url:
+                    openapi_url = calculate_relative_url(
+                        self.redoc_url, self.openapi_url
+                    )
+                else:
                     root_path = req.scope.get("root_path", "").rstrip("/")
                     openapi_url = root_path + self.openapi_url
                 return get_redoc_html(

fastapi/openapi/utils.py

@@ -1,7 +1,9 @@
 import http.client
 import inspect
 import warnings
+from os.path import basename, dirname, relpath
 from typing import Any, Dict, List, Optional, Sequence, Set, Tuple, Type, Union, cast
+from urllib.parse import urlparse
 
 from fastapi import routing
 from fastapi._compat import (
@@ -546,3 +548,35 @@ def get_openapi(
     if tags:
         output["tags"] = tags
     return jsonable_encoder(OpenAPI(**output), by_alias=True, exclude_none=True)  # type: ignore
+
+
+def calculate_relative_url(page_url: Optional[str], fetch_url: Optional[str]) -> str:
+    if page_url is None or fetch_url is None:
+        return fetch_url or ""
+
+    parsed_page_url = urlparse(page_url)
+    parsed_fetch_url = urlparse(fetch_url)
+
+    if (
+        parsed_page_url.scheme != parsed_fetch_url.scheme
+        or parsed_page_url.netloc != parsed_fetch_url.netloc
+    ):
+        return fetch_url
+
+    fetch_path = parsed_fetch_url.path
+    page_path = parsed_page_url.path
+    if not page_path.endswith("/"):
+        page_path = dirname(page_path) + "/"
+
+    relative_path = relpath(fetch_path, page_path)
+
+    if relative_path == ".":
+        return "./" if fetch_path.endswith("/") else basename(fetch_path)
+
+    if relative_path == "..":
+        return "../"
+
+    if not relative_path.startswith("/"):
+        relative_path = f"./{relative_path}"
+
+    return relative_path

tests/test_application.py

@@ -1,5 +1,6 @@
 import pytest
 from dirty_equals import IsDict
+from fastapi import FastAPI
 from fastapi.testclient import TestClient
 
 from .main import app
@@ -1281,3 +1282,20 @@ def test_openapi_schema():
             }
         },
     }
+
+
+def test_relative_docs():
+    _app = FastAPI(relative_docs=True)
+    _client = TestClient(_app)
+
+    response = _client.get("/docs")
+    assert response.status_code == 200, response.text
+    assert "./openapi.json" in response.text
+
+    response = _client.get("/redoc")
+    assert response.status_code == 200, response.text
+    assert "./openapi.json" in response.text
+
+    response = _client.get("/openapi.json")
+    assert response.status_code == 200, response.text
+    assert "../" in response.text

tests/test_local_docs.py

@@ -1,6 +1,7 @@
 import inspect
 
 from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.openapi.utils import calculate_relative_url
 
 
 def test_strings_in_generated_swagger():
@@ -65,3 +66,25 @@ def test_google_fonts_in_generated_redoc():
         openapi_url="/docs", title="title", with_google_fonts=False
     ).body.decode()
     assert "fonts.googleapis.com" not in body_without_google_fonts
+
+
+def test_calculate_relative_url() -> None:
+    assert calculate_relative_url("/docs/", "/docs/a.json") == "./a.json"
+    assert calculate_relative_url("/docs", "/docs/a.json") == "./docs/a.json"
+    assert calculate_relative_url("/docs/", "/docs/subdir/a.json") == "./subdir/a.json"
+    assert (
+        calculate_relative_url("/docs", "/docs/subdir/a.json") == "./docs/subdir/a.json"
+    )
+    assert calculate_relative_url("/", "/a.json") == "./a.json"
+    assert calculate_relative_url("/b.json", "/a.json") == "./a.json"
+    assert calculate_relative_url("/docs/a.json", "/docs/a.json") == "./a.json"
+    assert calculate_relative_url("/", "/docs/a.json") == "./docs/a.json"
+    assert calculate_relative_url("/docs", "/") == "./"
+    assert calculate_relative_url("/docs/", "/") == "../"
+
+    assert calculate_relative_url(None, "/any/path") == "/any/path"
+    assert calculate_relative_url("http://example.com", "/any/path") == "/any/path"
+    assert (
+        calculate_relative_url("http://example.com", "http://a.com/any/path")
+        == "http://a.com/any/path"
+    )