Added render_redoc_ui and redoc_url. Changed /docs/ -> /docs

mr-fatalyst · mr-fatalyst · commit 1e17ca4b699c · 2025-03-15T22:23:13.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,11 @@ All notable changes to FastOpenAPI are documented in this file.
 
 FastOpenAPI follows the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
 
+## [0.4.0] - Unreleased
+
+### Added
+- `ReDoc UI` and default URL (`host:port/redoc`)
+
 ## [0.3.1] - 2025-03-15
 
 ### Fixed
diff --git a/examples/falcon/run.py b/examples/falcon/run.py
@@ -10,7 +10,8 @@
     app=app,
     title="MyFalconApp",
     version="0.0.1",
-    docs_url="/docs/",
+    docs_url="/docs",
+    redoc_url="/redoc",
     openapi_version="3.0.0",
 )
 router.include_router(api_router, prefix="/api")
diff --git a/examples/falcon_example.py b/examples/falcon_example.py
@@ -5,7 +5,7 @@
 from fastopenapi.routers import FalconRouter
 
 app = falcon.asgi.App()
-router = FalconRouter(app=app, docs_url="/docs/", openapi_version="3.0.0")
+router = FalconRouter(app=app, docs_url="/docs", openapi_version="3.0.0")
 
 
 class HelloResponse(BaseModel):
diff --git a/examples/flask/run.py b/examples/flask/run.py
@@ -9,7 +9,8 @@
     app=app,
     title="MyFlaskApp",
     version="0.0.1",
-    docs_url="/docs/",
+    docs_url="/docs",
+    redoc_url="/redoc",
     openapi_version="3.0.0",
 )
 router.include_router(api_router, prefix="/api")
diff --git a/examples/flask_example.py b/examples/flask_example.py
@@ -4,7 +4,7 @@
 from fastopenapi.routers import FlaskRouter
 
 app = Flask(__name__)
-router = FlaskRouter(app=app, docs_url="/docs/", openapi_version="3.0.0")
+router = FlaskRouter(app=app, docs_url="/docs", openapi_version="3.0.0")
 
 
 class HelloResponse(BaseModel):
diff --git a/examples/quart/run.py b/examples/quart/run.py
@@ -9,7 +9,8 @@
     app=app,
     title="MyQuartApp",
     version="0.0.1",
-    docs_url="/docs/",
+    docs_url="/docs",
+    redoc_url="/redoc",
     openapi_version="3.0.0",
 )
 router.include_router(api_router, prefix="/api")
diff --git a/examples/quart_example.py b/examples/quart_example.py
@@ -4,7 +4,7 @@
 from fastopenapi.routers import QuartRouter
 
 app = Quart(__name__)
-router = QuartRouter(app=app, docs_url="/docs/", openapi_version="3.0.0")
+router = QuartRouter(app=app, docs_url="/docs", openapi_version="3.0.0")
 
 
 class HelloResponse(BaseModel):
diff --git a/examples/sanic/run.py b/examples/sanic/run.py
@@ -10,7 +10,8 @@
     app=app,
     title="MySanicApp",
     version="0.0.1",
-    docs_url="/docs/",
+    docs_url="/docs",
+    redoc_url="/redoc",
     openapi_version="3.0.0",
 )
 router.include_router(api_router, prefix="/api")
diff --git a/examples/sanic_example.py b/examples/sanic_example.py
@@ -4,7 +4,7 @@
 from fastopenapi.routers import SanicRouter
 
 app = Sanic("MySanicApp")
-router = SanicRouter(app=app, docs_url="/docs/", openapi_version="3.0.0")
+router = SanicRouter(app=app, docs_url="/docs", openapi_version="3.0.0")
 
 
 class HelloResponse(BaseModel):
diff --git a/examples/starlette/run.py b/examples/starlette/run.py
@@ -10,7 +10,8 @@
     app=app,
     title="MyStarletteApp",
     version="0.0.1",
-    docs_url="/docs/",
+    docs_url="/docs",
+    redoc_url="/redoc",
     openapi_version="3.0.0",
 )
 router.include_router(api_router, prefix="/api")
diff --git a/examples/starlette_example.py b/examples/starlette_example.py
@@ -5,7 +5,7 @@
 from fastopenapi.routers import StarletteRouter
 
 app = Starlette()
-router = StarletteRouter(app=app, docs_url="/docs/", openapi_version="3.0.0")
+router = StarletteRouter(app=app, docs_url="/docs", openapi_version="3.0.0")
 
 
 class HelloResponse(BaseModel):
diff --git a/fastopenapi/__init__.py b/fastopenapi/__init__.py
@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.4.0"
diff --git a/fastopenapi/base_router.py b/fastopenapi/base_router.py
@@ -8,6 +8,7 @@
 from pydantic import BaseModel
 
 SWAGGER_URL = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.20.0/"
+REDOC_URL = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"
 
 PYTHON_TYPE_MAPPING = {
     int: "integer",
@@ -26,8 +27,10 @@ class BaseRouter:
     **Parameters**:
     - `app`: The web framework application instance (e.g., Flask, Falcon, etc.).
     If provided, documentation and schema routes are automatically added to the app.
-    - `docs_url`: URL path prefix where the documentation UI will be served
-    (defaults to "/docs/").
+    - `docs_url`: URL path prefix where the Swagger documentation UI will be served
+    (defaults to "/docs").
+    - `redoc_url`: URL path prefix where the Redoc documentation UI will be served
+    (defaults to "/docs").
     - `openapi_url`: URL path where the OpenAPI JSON schema will be served
     (defaults to "/openapi.json").
     - `openapi_version`: OpenAPI version for the schema (defaults to "3.0.0").
@@ -48,7 +51,8 @@ class BaseRouter:
     def __init__(
         self,
         app: Any = None,
-        docs_url: str = "/docs/",
+        docs_url: str = "/docs",
+        redoc_url: str = "/redoc",
         openapi_url: str = "/openapi.json",
         openapi_version: str = "3.0.0",
         title: str = "My App",
@@ -59,6 +63,7 @@ def __init__(
     ):
         self.app = app
         self.docs_url = docs_url
+        self.redoc_url = redoc_url
         self.openapi_url = openapi_url
         self.openapi_version = openapi_version
         self.title = title
@@ -295,6 +300,29 @@ def render_swagger_ui(openapi_json_url: str) -> str:
         </html>
         """
 
+    @staticmethod
+    def render_redoc_ui(openapi_json_url: str) -> str:
+        return f"""
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <title>ReDoc</title>
+            <meta charset="utf-8"/>
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <style>
+              body {{
+                margin: 0;
+                padding: 0;
+              }}
+            </style>
+          </head>
+          <body>
+            <redoc spec-url='{openapi_json_url}'></redoc>
+            <script src="{REDOC_URL}"></script>
+          </body>
+        </html>
+        """
+
     @staticmethod
     def resolve_endpoint_params(
         endpoint: Callable, all_params: dict, body: dict
diff --git a/fastopenapi/routers/falcon.py b/fastopenapi/routers/falcon.py
@@ -118,4 +118,11 @@ async def on_get(inner_self, req, resp):
                 resp.content_type = "text/html"
                 resp.text = html
 
+        class RedocUIResource:
+            async def on_get(inner_self, req, resp):
+                html = outer.render_redoc_ui(outer.openapi_url)
+                resp.content_type = "text/html"
+                resp.text = html
+
         self.app.add_route(self.docs_url, SwaggerUIResource())
+        self.app.add_route(self.redoc_url, RedocUIResource())
diff --git a/fastopenapi/routers/flask.py b/fastopenapi/routers/flask.py
@@ -56,3 +56,8 @@ def openapi_view():
         def docs_view():
             html = self.render_swagger_ui(self.openapi_url)
             return Response(html, mimetype="text/html")
+
+        @self.app.route(self.redoc_url, methods=["GET"])
+        def redoc_view():
+            html = self.render_redoc_ui(self.openapi_url)
+            return Response(html, mimetype="text/html")
diff --git a/fastopenapi/routers/quart.py b/fastopenapi/routers/quart.py
@@ -60,3 +60,8 @@ async def openapi_view():
         async def docs_view():
             html = self.render_swagger_ui(self.openapi_url)
             return Response(html, mimetype="text/html")
+
+        @self.app.route(self.redoc_url, methods=["GET"])
+        async def redoc_view():
+            html = self.render_redoc_ui(self.openapi_url)
+            return Response(html, mimetype="text/html")
diff --git a/fastopenapi/routers/sanic.py b/fastopenapi/routers/sanic.py
@@ -69,3 +69,8 @@ async def openapi_view(request):
         async def docs_view(request):
             html = self.render_swagger_ui(self.openapi_url)
             return response.html(html)
+
+        @self.app.route(self.redoc_url, methods=["GET"])
+        async def redoc_view(request):
+            html = self.render_redoc_ui(self.openapi_url)
+            return response.html(html)
diff --git a/fastopenapi/routers/starlette.py b/fastopenapi/routers/starlette.py
@@ -76,7 +76,14 @@ async def docs_view(request):
             html = self.render_swagger_ui(self.openapi_url)
             return HTMLResponse(html)
 
+        async def redoc_view(request):
+            html = self.render_redoc_ui(self.openapi_url)
+            return HTMLResponse(html)
+
         self.app.router.routes.append(
             Route(self.openapi_url, openapi_view, methods=["GET"])
         )
         self.app.router.routes.append(Route(self.docs_url, docs_view, methods=["GET"]))
+        self.app.router.routes.append(
+            Route(self.redoc_url, redoc_view, methods=["GET"])
+        )
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "fastopenapi"
-version = "0.3.1"
+version = "0.4.0"
 description = "FastOpenAPI is a library for generating and integrating OpenAPI schemas using Pydantic."
 authors = [
     {name = "Nikita Ryzhenkov", email = "nikita.ryzhenkoff@gmail.com"}
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -38,3 +38,7 @@ def echo_both(x: int, item: Item):
 
 def echo(x: Any):
     return x
+
+
+def async_echo(x: Any):
+    return x
diff --git a/tests/test_base_router.py b/tests/test_base_router.py
@@ -1,7 +1,7 @@
 import pytest
 from pydantic import BaseModel
 
-from fastopenapi.base_router import SWAGGER_URL, BaseRouter
+from fastopenapi.base_router import REDOC_URL, SWAGGER_URL, BaseRouter
 
 from .conftest import Item, echo_int, return_item_model
 
@@ -337,6 +337,15 @@ def test_render_swagger_ui_html():
     assert SWAGGER_URL.strip("/") in html
 
 
+def test_render_redoc_ui_html():
+    url = "/test/openapi.json"
+    html = BaseRouter.render_redoc_ui(url)
+    assert "<html" in html
+    assert "ReDoc" in html
+    assert url in html
+    assert REDOC_URL.strip("/") in html
+
+
 def test_register_docs_endpoints_not_implemented():
     class NotImplementedRouter(BaseRouter):
         pass
diff --git a/tests/test_falcon_router.py b/tests/test_falcon_router.py
@@ -84,7 +84,7 @@ def __init__(self):
 @pytest.fixture
 def falcon_app():
     app = falcon.asgi.App()
-    router = FalconRouter(app=app, docs_url="/docs/")
+    router = FalconRouter(app=app)
     return app, router
 
 
@@ -156,9 +156,12 @@ def test_falcon_docs_endpoints(falcon_app):
     client = testing.TestClient(app)
     result = client.simulate_get("/openapi.json")
     assert result.status_code == 200 and "openapi" in result.json
-    result = client.simulate_get("/docs/")
+    result = client.simulate_get("/docs")
     assert result.status_code == 200
     assert "<title>Swagger UI</title>" in result.text
+    result = client.simulate_get("/redoc")
+    assert result.status_code == 200
+    assert "<title>ReDoc</title>" in result.text
 
 
 def test_get_falcon_status_unknown():
@@ -212,12 +215,12 @@ def test_create_or_update_resource_reuse():
 
 def test_register_docs_endpoints():
     app = DummyApp()
-    router = FalconRouter(app=app, docs_url="/docs/", openapi_url="/openapi.json")
+    router = FalconRouter(app=app)
     router._openapi_schema = {"openapi": "3.0.0"}
     router.render_swagger_ui = lambda url: "<html>Swagger UI</html>"
     router._register_docs_endpoints()
     assert "/openapi.json" in app.routes
-    assert "/docs/" in app.routes
+    assert "/docs" in app.routes
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_flask_router.py b/tests/test_flask_router.py
@@ -16,7 +16,7 @@
 def flask_app():
     app = Flask(__name__)
     app.testing = True
-    router = FlaskRouter(app=app, docs_url="/docs/")
+    router = FlaskRouter(app=app)
     return app, router
 
 
@@ -99,14 +99,19 @@ def test_flask_docs_endpoints(flask_app):
     schema = res.get_json()
     assert "openapi" in schema and "paths" in schema and "components" in schema
 
-    res = client.get("/docs/")
+    res = client.get("/docs")
     assert res.status_code == 200
     html_text = res.data.decode()
     assert "<title>Swagger UI</title>" in html_text
 
+    res = client.get("/redoc")
+    assert res.status_code == 200
+    html_text = res.data.decode()
+    assert "<title>ReDoc</title>" in html_text
+
 
 def test_flask_add_route_no_app():
-    router = FlaskRouter(app=None, docs_url="/docs/", openapi_url="/openapi.json")
+    router = FlaskRouter(app=None)
 
     def dummy_endpoint(x: int):
         return {"x": x}
diff --git a/tests/test_quart_router.py b/tests/test_quart_router.py
@@ -17,7 +17,7 @@
 def quart_app():
     app = Quart(__name__)
     app.testing = True
-    router = QuartRouter(app=app, docs_url="/docs/")
+    router = QuartRouter(app=app)
     return app, router
 
 
@@ -108,15 +108,20 @@ async def test_quart_docs_endpoints(quart_app):
     schema = await res.get_json()
     assert "openapi" in schema and "paths" in schema and "components" in schema
 
-    res = await client.get("/docs/")
+    res = await client.get("/docs")
     assert res.status_code == 200
     data = await res.data
     html_text = data.decode()
     assert "<title>Swagger UI</title>" in html_text
+    res = await client.get("/redoc")
+    assert res.status_code == 200
+    data = await res.data
+    html_text = data.decode()
+    assert "<title>ReDoc</title>" in html_text
 
 
 def test_quart_add_route_no_app():
-    router = QuartRouter(app=None, docs_url="/docs/", openapi_url="/openapi.json")
+    router = QuartRouter(app=None)
 
     def dummy_endpoint(x: int):
         return {"x": x}
diff --git a/tests/test_sanic_router.py b/tests/test_sanic_router.py
@@ -10,7 +10,7 @@
 @pytest.fixture
 def sanic_app():
     app = Sanic("test_app")
-    router = SanicRouter(app=app, docs_url="/docs/")
+    router = SanicRouter(app=app)
     try:
         from sanic_testing import TestManager
 
@@ -97,10 +97,14 @@ def test_sanic_docs_endpoints(sanic_app):
     assert response_obj.status == 200
     schema = response_obj.json
     assert "openapi" in schema and "paths" in schema
-    request, response_obj = client.get("/docs/")
+    request, response_obj = client.get("/docs")
     assert response_obj.status == 200
     text = response_obj.text
     assert "<title>Swagger UI</title>" in text
+    request, response_obj = client.get("/redoc")
+    assert response_obj.status == 200
+    text = response_obj.text
+    assert "<title>ReDoc</title>" in text
 
 
 def test_add_route_with_no_app():
diff --git a/tests/test_starlette_router.py b/tests/test_starlette_router.py
