From 98af95ddce09f3e621489e461514c69177ca2bcb Mon Sep 17 00:00:00 2001 From: gshmu Date: Fri, 11 Oct 2024 10:40:57 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Add=20relative=20docs=20everywhere?= =?UTF-8?q?=20(#12421)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/applications.py | 24 ++++++++++++++++++++---- fastapi/openapi/utils.py | 34 ++++++++++++++++++++++++++++++++++ tests/test_application.py | 18 ++++++++++++++++++ tests/test_local_docs.py | 23 +++++++++++++++++++++++ 4 files changed, 95 insertions(+), 4 deletions(-) diff --git a/fastapi/applications.py b/fastapi/applications.py index 6d427cdc2..c23bbb77d 100644 --- a/fastapi/applications.py +++ b/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,7 +1019,12 @@ class FastAPI(Starlette): async def swagger_ui_html(req: Request) -> HTMLResponse: root_path = req.scope.get("root_path", "").rstrip("/") - openapi_url = root_path + self.openapi_url + 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: oauth2_redirect_url = root_path + oauth2_redirect_url @@ -1040,8 +1051,13 @@ class FastAPI(Starlette): if self.openapi_url and self.redoc_url: async def redoc_html(req: Request) -> HTMLResponse: - root_path = req.scope.get("root_path", "").rstrip("/") - openapi_url = root_path + self.openapi_url + 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( openapi_url=openapi_url, title=f"{self.title} - ReDoc" ) diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py index 947eca948..5f44a4782 100644 --- a/fastapi/openapi/utils.py +++ b/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 diff --git a/tests/test_application.py b/tests/test_application.py index 5c62f5f6e..79ab5a33d 100644 --- a/tests/test_application.py +++ b/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 diff --git a/tests/test_local_docs.py b/tests/test_local_docs.py index 5f102edf1..5f527b135 100644 --- a/tests/test_local_docs.py +++ b/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" + )