🔖 Release 0.24.0

Pipfile

@@ -25,8 +25,8 @@ sqlalchemy = "*"
 uvicorn = "*"
 
 [packages]
-starlette = "==0.11.1"
-pydantic = "==0.25.0"
+starlette = "==0.12.0"
+pydantic = "==0.26.0"
 databases = {extras = ["sqlite"],version = "*"}
 hypercorn = "*"
 

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "3366422de5c4cdc49b82ebef5fe9268c48c8582a444a4fa1ae304dcb2654c469"
+            "sha256": "4a33b47e814fa75533548874ffadbc6163b3058db4d1615ff633512366d72ccb"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -21,7 +21,6 @@
                 "sha256:885daf8261818767d8f7cbd79f9d4482d118f024b6586ef6e67980236a27bfa3",
                 "sha256:f027372dc48641f683c559f247bd84962becaacdc9ba711d583c3871fb5652aa"
             ],
-            "markers": "python_version < '3.7'",
             "version": "==0.2.2"
         },
         "aiosqlite": {
@@ -114,11 +113,11 @@
         },
         "pydantic": {
             "hashes": [
-                "sha256:2203e01c1d87a3d964aa0db56efdb1b89a90eca610ab3f0ddea396e2a5fa4cc4",
-                "sha256:ac207906e78b1cafbbff6d57b0ce51b989cf5361d2487013f0b353f3bb3b8442"
+                "sha256:b72e0df2463cee746cf42639845d4106c19f30136375e779352d710e69617731",
+                "sha256:dab99d3070e040b8b2e987dfbe237350ab92d5d57a22d4e0e268ede2d85c7964"
             ],
             "index": "pypi",
-            "version": "==0.25.0"
+            "version": "==0.26.0"
         },
         "pytoml": {
             "hashes": [
@@ -134,10 +133,10 @@
         },
         "starlette": {
             "hashes": [
-                "sha256:9d48b35d1fc7521d59ae53c421297ab3878d3c7cd4b75266d77f6c73cccb78bb"
+                "sha256:d313433ef5cc38e0a276b59688ca2b11b8f031c78808c1afdf9d55cb86f34590"
             ],
             "index": "pypi",
-            "version": "==0.11.1"
+            "version": "==0.12.0"
         },
         "typing-extensions": {
             "hashes": [
@@ -348,10 +347,10 @@
         },
         "ipykernel": {
             "hashes": [
-                "sha256:0aeb7ec277ac42cc2b59ae3d08b10909b2ec161dc6908096210527162b53675d",
-                "sha256:0fc0bf97920d454102168ec2008620066878848fcfca06c22b669696212e292f"
+                "sha256:346189536b88859937b5f4848a6fd85d1ad0729f01724a411de5cae9b618819c",
+                "sha256:f0e962052718068ad3b1d8bcc703794660858f58803c3798628817f492a8769c"
             ],
-            "version": "==5.1.0"
+            "version": "==5.1.1"
         },
         "ipython": {
             "hashes": [
@@ -377,11 +376,11 @@
         },
         "isort": {
             "hashes": [
-                "sha256:49293e2ff590cc8d48bc1f51970548b5b102bf038439ca1af77f352164725628",
-                "sha256:ba69a4be8474be11720636bc2f0cf66f7054d417d4c1dbc1dfe504bb8e739541"
+                "sha256:c40744b6bc5162bbb39c1257fe298b7a393861d50978b565f3ccd9cb9de0182a",
+                "sha256:f57abacd059dc3bd666258d1efb0377510a89777fda3e3274e3c01f7c03ae22d"
             ],
             "index": "pypi",
-            "version": "==4.3.19"
+            "version": "==4.3.20"
         },
         "jedi": {
             "hashes": [
@@ -443,10 +442,10 @@
         },
         "markdown": {
             "hashes": [
-                "sha256:fc4a6f69a656b8d858d7503bda633f4dd63c2d70cf80abdc6eafa64c4ae8c250",
-                "sha256:fe463ff51e679377e3624984c829022e2cfb3be5518726b06f608a07a3aad680"
+                "sha256:2e50876bcdd74517e7b71f3e7a76102050edec255b3983403f1a63e7c8a41e7a",
+                "sha256:56a46ac655704b91e5b7e6326ce43d5ef72411376588afa1dd90e881b83c7e8c"
             ],
-            "version": "==3.1"
+            "version": "==3.1.1"
         },
         "markdown-include": {
             "hashes": [
@@ -512,11 +511,11 @@
         },
         "mkdocs-material": {
             "hashes": [
-                "sha256:4ffe7d8c0c3c53c5313a910c14a88820be74beebb53ed14c9056e521ea9793d5",
-                "sha256:d64b9555ae4ee86fe07a18612c9bd488f3b74a0afd3d9ead7e29efc59d98ca80"
+                "sha256:1c39b6af13a900d9f47ab2b8ac67b3258799f4570b552573e9d6868ad6a438e9",
+                "sha256:22073941cff7176e810b719aced6a90381e64a96d346b8a6803a06b7192b7ad5"
             ],
             "index": "pypi",
-            "version": "==4.2.0"
+            "version": "==4.3.0"
         },
         "more-itertools": {
             "hashes": [
@@ -760,11 +759,11 @@
         },
         "requests": {
             "hashes": [
-                "sha256:502a824f31acdacb3a35b6690b5fbf0bc41d63a24a45c4004352b0242707598e",
-                "sha256:7bf2a778576d825600030a110f3c0e3e8edc51dfaafe1c146e39a2027784957b"
+                "sha256:11e007a8a2aa0323f5a921e9e6a2d7e4e67d9877e85773fba9ba6419025cbeb4",
+                "sha256:9cf5292fcd0f598c671cfc1e0d7d1a7f13bb8085e9a590f48c010551dc6c4b31"
             ],
             "index": "pypi",
-            "version": "==2.21.0"
+            "version": "==2.22.0"
         },
         "send2trash": {
             "hashes": [
@@ -859,10 +858,10 @@
         },
         "urllib3": {
             "hashes": [
-                "sha256:2393a695cd12afedd0dcb26fe5d50d0cf248e5a66f75dbd89a3d4eb333a61af4",
-                "sha256:a637e5fae88995b256e3409dc4d52c2e2e0ba32c42a6365fee8bbd2238de3cfb"
+                "sha256:a53063d8b9210a7bdec15e7b272776b9d42b2fd6816401a0d43006ad2f9902db",
+                "sha256:d363e3607d8de0c220d31950a8f38b18d5ba7c0830facd71a1c6b1036b7ce06c"
             ],
-            "version": "==1.24.3"
+            "version": "==1.25.2"
         },
         "uvicorn": {
             "hashes": [

docs/release-notes.md

@@ -1,5 +1,41 @@
 ## Next release
 
+## 0.24.0
+
+* Add support for WebSockets with dependencies and parameters.
+    * Support included for:
+        * `Depends`
+        * `Security`
+        * `Cookie`
+        * `Header`
+        * `Path`
+        * `Query`
+        * ...as these are compatible with the WebSockets protocol (e.g. `Body` is not).
+    * [Updated documentation for WebSockets](https://fastapi.tiangolo.com/tutorial/websockets/).
+    * PR [#178](https://github.com/tiangolo/fastapi/pull/178) by [@jekirl](https://github.com/jekirl).
+
+* Upgrade the compatible version of Pydantic to `0.26.0`.
+    * This includes JSON Schema support for IP address and network objects, bug fixes, and other features.
+    * PR [#247](https://github.com/tiangolo/fastapi/pull/247) by [@euri10](https://github.com/euri10).
+
+## 0.23.0
+
+* Upgrade the compatible version of Starlette to `0.12.0`.
+    * This includes support for ASGI 3 (the latest version of the standard).
+    * It's now possible to use [Starlette's `StreamingResponse`](https://www.starlette.io/responses/#streamingresponse) with iterators, like [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) objects (as those returned by `open()`).
+    * It's now possible to use the low level utility `iterate_in_threadpool` from `starlette.concurrency` (for advanced scenarios).
+    * PR [#243](https://github.com/tiangolo/fastapi/pull/243).
+
+* Add OAuth2 redirect page for Swagger UI. This allows having delegated authentication in the Swagger UI docs. For this to work, you need to add `{your_origin}/docs/oauth2-redirect` to the allowed callbacks in your OAuth2 provider (in Auth0, Facebook, Google, etc).
+    * For example, during development, it could be `http://localhost:8000/docs/oauth2-redirect`.
+    * Have in mind that this callback URL is independent of whichever one is used by your frontend. You might also have another callback at `https://yourdomain.com/login/callback`.
+    * This is only to allow delegated authentication in the API docs with Swagger UI.
+    * PR [#198](https://github.com/tiangolo/fastapi/pull/198) by [@steinitzu](https://github.com/steinitzu).
+
+* Make Swagger UI and ReDoc route handlers (*path operations*) be `async` functions instead of lambdas to improve performance. PR [#241](https://github.com/tiangolo/fastapi/pull/241) by [@Trim21](https://github.com/Trim21).
+
+* Make Swagger UI and ReDoc URLs parameterizable, allowing to host and serve local versions of them and have offline docs. PR [#112](https://github.com/tiangolo/fastapi/pull/112) by [@euri10](https://github.com/euri10).
+
 ## 0.22.0
 
 * Add support for `dependencies` parameter:

docs/src/websockets/tutorial001.py

@@ -44,10 +44,9 @@ async def get():
     return HTMLResponse(html)
 
 
-@app.websocket_route("/ws")
+@app.websocket("/ws")
 async def websocket_endpoint(websocket: WebSocket):
     await websocket.accept()
     while True:
         data = await websocket.receive_text()
         await websocket.send_text(f"Message text was: {data}")
-    await websocket.close()

docs/src/websockets/tutorial002.py

@@ -0,0 +1,78 @@
+from fastapi import Cookie, Depends, FastAPI, Header
+from starlette.responses import HTMLResponse
+from starlette.status import WS_1008_POLICY_VIOLATION
+from starlette.websockets import WebSocket
+
+app = FastAPI()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Chat</title>
+    </head>
+    <body>
+        <h1>WebSocket Chat</h1>
+        <form action="" onsubmit="sendMessage(event)">
+            <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
+            <button onclick="connect(event)">Connect</button>
+            <br>
+            <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
+            <button>Send</button>
+        </form>
+        <ul id='messages'>
+        </ul>
+        <script>
+        var ws = null;
+            function connect(event) {
+                var input = document.getElementById("itemId")
+                ws = new WebSocket("ws://localhost:8000/items/" + input.value + "/ws");
+                ws.onmessage = function(event) {
+                    var messages = document.getElementById('messages')
+                    var message = document.createElement('li')
+                    var content = document.createTextNode(event.data)
+                    message.appendChild(content)
+                    messages.appendChild(message)
+                };
+            }
+            function sendMessage(event) {
+                var input = document.getElementById("messageText")
+                ws.send(input.value)
+                input.value = ''
+                event.preventDefault()
+            }
+        </script>
+    </body>
+</html>
+"""
+
+
+@app.get("/")
+async def get():
+    return HTMLResponse(html)
+
+
+async def get_cookie_or_client(
+    websocket: WebSocket, session: str = Cookie(None), x_client: str = Header(None)
+):
+    if session is None and x_client is None:
+        await websocket.close(code=WS_1008_POLICY_VIOLATION)
+    return session or x_client
+
+
+@app.websocket("/items/{item_id}/ws")
+async def websocket_endpoint(
+    websocket: WebSocket,
+    item_id: int,
+    q: str = None,
+    cookie_or_client: str = Depends(get_cookie_or_client),
+):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_text()
+        await websocket.send_text(
+            f"Session Cookie or X-Client Header value is: {cookie_or_client}"
+        )
+        if q is not None:
+            await websocket.send_text(f"Query parameter q is: {q}")
+        await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")

docs/tutorial/websockets.md

@@ -27,9 +27,9 @@ But it's the simplest way to focus on the server-side of WebSockets and have a w
 {!./src/websockets/tutorial001.py!}
 ```
 
-## Create a `websocket_route`
+## Create a `websocket`
 
-In your **FastAPI** application, create a `websocket_route`:
+In your **FastAPI** application, create a `websocket`:
 
 ```Python hl_lines="3 47 48"
 {!./src/websockets/tutorial001.py!}
@@ -38,15 +38,6 @@ In your **FastAPI** application, create a `websocket_route`:
 !!! tip
     In this example we are importing `WebSocket` from `starlette.websockets` to use it in the type declaration in the WebSocket route function.
 
-    That is not required, but it's recommended as it will provide you completion and checks inside the function.
-
-
-!!! info
-    This `websocket_route` we are using comes directly from <a href="https://www.starlette.io/applications/" target="_blank">Starlette</a>. 
-    
-    That's why the naming convention is not the same as with other API path operations (`get`, `post`, etc).
-
-
 ## Await for messages and send messages
 
 In your WebSocket route you can `await` for messages and send messages.
@@ -57,6 +48,32 @@ In your WebSocket route you can `await` for messages and send messages.
 
 You can receive and send binary, text, and JSON data.
 
+## Using `Depends` and others
+
+In WebSocket endpoints you can import from `fastapi` and use:
+
+* `Depends`
+* `Security`
+* `Cookie`
+* `Header`
+* `Path`
+* `Query`
+
+They work the same way as for other FastAPI endpoints/*path operations*:
+
+```Python hl_lines="55 56 57 58 59 60 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78"
+{!./src/websockets/tutorial002.py!}
+```
+
+!!! info
+    In a WebSocket it doesn't really make sense to raise an `HTTPException`. So it's better to close the WebSocket connection directly.
+
+    You can use a closing code from the <a href="https://tools.ietf.org/html/rfc6455#section-7.4.1" target="_blank">valid codes defined in the specification</a>.
+
+    In the future, there will be a `WebSocketException` that you will be able to `raise` from anywhere, and add exception handlers for it. It depends on the <a href="https://github.com/encode/starlette/pull/527" target="_blank">PR #527</a> in Starlette.
+
+## More info
+
 To learn more about the options, check Starlette's documentation for:
 
 * <a href="https://www.starlette.io/applications/" target="_blank">Applications (`websocket_route`)</a>.

fastapi/__init__.py

@@ -1,6 +1,6 @@
 """FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
 
-__version__ = "0.22.0"
+__version__ = "0.24.0"
 
 from starlette.background import BackgroundTasks
 

fastapi/applications.py

@@ -1,7 +1,11 @@
 from typing import Any, Callable, Dict, List, Optional, Type, Union
 
 from fastapi import routing
-from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.openapi.docs import (
+    get_redoc_html,
+    get_swagger_ui_html,
+    get_swagger_ui_oauth2_redirect_html,
+)
 from fastapi.openapi.utils import get_openapi
 from fastapi.params import Depends
 from pydantic import BaseModel
@@ -9,7 +13,7 @@ from starlette.applications import Starlette
 from starlette.exceptions import ExceptionMiddleware, HTTPException
 from starlette.middleware.errors import ServerErrorMiddleware
 from starlette.requests import Request
-from starlette.responses import JSONResponse, Response
+from starlette.responses import HTMLResponse, JSONResponse, Response
 from starlette.routing import BaseRoute
 
 
@@ -36,6 +40,7 @@ class FastAPI(Starlette):
         openapi_prefix: str = "",
         docs_url: Optional[str] = "/docs",
         redoc_url: Optional[str] = "/redoc",
+        swagger_ui_oauth2_redirect_url: Optional[str] = "/docs/oauth2-redirect",
         **extra: Dict[str, Any],
     ) -> None:
         self._debug = debug
@@ -52,6 +57,7 @@ class FastAPI(Starlette):
         self.openapi_prefix = openapi_prefix.rstrip("/")
         self.docs_url = docs_url
         self.redoc_url = redoc_url
+        self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url
         self.extra = extra
 
         self.openapi_version = "3.0.2"
@@ -79,29 +85,41 @@ class FastAPI(Starlette):
 
     def setup(self) -> None:
         if self.openapi_url:
-            self.add_route(
-                self.openapi_url,
-                lambda req: JSONResponse(self.openapi()),
-                include_in_schema=False,
-            )
+
+            async def openapi(req: Request) -> JSONResponse:
+                return JSONResponse(self.openapi())
+
+            self.add_route(self.openapi_url, openapi, include_in_schema=False)
+            openapi_url = self.openapi_prefix + self.openapi_url
         if self.openapi_url and self.docs_url:
-            self.add_route(
-                self.docs_url,
-                lambda r: get_swagger_ui_html(
-                    openapi_url=self.openapi_prefix + self.openapi_url,
+
+            async def swagger_ui_html(req: Request) -> HTMLResponse:
+                return get_swagger_ui_html(
+                    openapi_url=openapi_url,
                     title=self.title + " - Swagger UI",
-                ),
-                include_in_schema=False,
-            )
+                    oauth2_redirect_url=self.swagger_ui_oauth2_redirect_url,
+                )
+
+            self.add_route(self.docs_url, swagger_ui_html, include_in_schema=False)
+
+            if self.swagger_ui_oauth2_redirect_url:
+
+                async def swagger_ui_redirect(req: Request) -> HTMLResponse:
+                    return get_swagger_ui_oauth2_redirect_html()
+
+                self.add_route(
+                    self.swagger_ui_oauth2_redirect_url,
+                    swagger_ui_redirect,
+                    include_in_schema=False,
+                )
         if self.openapi_url and self.redoc_url:
-            self.add_route(
-                self.redoc_url,
-                lambda r: get_redoc_html(
-                    openapi_url=self.openapi_prefix + self.openapi_url,
-                    title=self.title + " - ReDoc",
-                ),
-                include_in_schema=False,
-            )
+
+            async def redoc_html(req: Request) -> HTMLResponse:
+                return get_redoc_html(
+                    openapi_url=openapi_url, title=self.title + " - ReDoc"
+                )
+
+            self.add_route(self.redoc_url, redoc_html, include_in_schema=False)
         self.add_exception_handler(HTTPException, http_exception)
 
     def add_api_route(
@@ -185,6 +203,18 @@ class FastAPI(Starlette):
 
         return decorator
 
+    def add_api_websocket_route(
+        self, path: str, endpoint: Callable, name: str = None
+    ) -> None:
+        self.router.add_api_websocket_route(path, endpoint, name=name)
+
+    def websocket(self, path: str, name: str = None) -> Callable:
+        def decorator(func: Callable) -> Callable:
+            self.add_api_websocket_route(path, func, name=name)
+            return func
+
+        return decorator
+
     def include_router(
         self,
         router: routing.APIRouter,

fastapi/dependencies/models.py

@@ -26,6 +26,7 @@ class Dependant:
         name: str = None,
         call: Callable = None,
         request_param_name: str = None,
+        websocket_param_name: str = None,
         background_tasks_param_name: str = None,
         security_scopes_param_name: str = None,
         security_scopes: List[str] = None,
@@ -38,6 +39,7 @@ class Dependant:
         self.dependencies = dependencies or []
         self.security_requirements = security_schemes or []
         self.request_param_name = request_param_name
+        self.websocket_param_name = websocket_param_name
         self.background_tasks_param_name = background_tasks_param_name
         self.security_scopes = security_scopes
         self.security_scopes_param_name = security_scopes_param_name

fastapi/dependencies/utils.py

@@ -33,6 +33,7 @@ from starlette.background import BackgroundTasks
 from starlette.concurrency import run_in_threadpool
 from starlette.datastructures import FormData, Headers, QueryParams, UploadFile
 from starlette.requests import Request
+from starlette.websockets import WebSocket
 
 param_supported_types = (
     str,
@@ -184,6 +185,8 @@ def get_dependant(
             )
         elif lenient_issubclass(param.annotation, Request):
             dependant.request_param_name = param_name
+        elif lenient_issubclass(param.annotation, WebSocket):
+            dependant.websocket_param_name = param_name
         elif lenient_issubclass(param.annotation, BackgroundTasks):
             dependant.background_tasks_param_name = param_name
         elif lenient_issubclass(param.annotation, SecurityScopes):
@@ -279,7 +282,7 @@ def is_coroutine_callable(call: Callable) -> bool:
 
 async def solve_dependencies(
     *,
-    request: Request,
+    request: Union[Request, WebSocket],
     dependant: Dependant,
     body: Dict[str, Any] = None,
     background_tasks: BackgroundTasks = None,
@@ -326,8 +329,10 @@ async def solve_dependencies(
         )
         values.update(body_values)
         errors.extend(body_errors)
-    if dependant.request_param_name:
+    if dependant.request_param_name and isinstance(request, Request):
         values[dependant.request_param_name] = request
+    elif dependant.websocket_param_name and isinstance(request, WebSocket):
+        values[dependant.websocket_param_name] = request
     if dependant.background_tasks_param_name:
         if background_tasks is None:
             background_tasks = BackgroundTasks()

fastapi/openapi/docs.py

@@ -1,80 +1,158 @@
+from typing import Optional
+
 from starlette.responses import HTMLResponse
 
 
-def get_swagger_ui_html(*, openapi_url: str, title: str) -> HTMLResponse:
-    return HTMLResponse(
-        """
+def get_swagger_ui_html(
+    *,
+    openapi_url: str,
+    title: str,
+    swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-bundle.js",
+    swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css",
+    swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+    oauth2_redirect_url: Optional[str] = None,
+) -> HTMLResponse:
+
+    html = f"""
     <! doctype html>
     <html>
     <head>
-    <link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css">
-    <link rel="shortcut icon" href="https://fastapi.tiangolo.com/img/favicon.png">
-    <title>
-    """
-        + title
-        + """
-    </title>
+    <link type="text/css" rel="stylesheet" href="{swagger_css_url}">
+    <link rel="shortcut icon" href="{swagger_favicon_url}">
+    <title>{title}</title>
     </head>
     <body>
     <div id="swagger-ui">
     </div>
-    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+    <script src="{swagger_js_url}"></script>
     <!-- `SwaggerUIBundle` is now available on the page -->
     <script>
-            
-    const ui = SwaggerUIBundle({
-        url: '"""
-        + openapi_url
-        + """',
+    const ui = SwaggerUIBundle({{
+        url: '{openapi_url}',
+    """
+
+    if oauth2_redirect_url:
+        html += f"oauth2RedirectUrl: window.location.origin + '{oauth2_redirect_url}',"
+
+    html += """
         dom_id: '#swagger-ui',
         presets: [
         SwaggerUIBundle.presets.apis,
         SwaggerUIBundle.SwaggerUIStandalonePreset
         ],
-        layout: "BaseLayout",
-        deepLinking: true
- 
+        layout: "BaseLayout"
     })
     </script>
     </body>
     </html>
     """
-    )
+    return HTMLResponse(html)
 
 
-def get_redoc_html(*, openapi_url: str, title: str) -> HTMLResponse:
-    return HTMLResponse(
-        """
+def get_redoc_html(
+    *,
+    openapi_url: str,
+    title: str,
+    redoc_js_url: str = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js",
+    redoc_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+) -> HTMLResponse:
+    html = f"""
     <!DOCTYPE html>
-<html>
-  <head>
-    <title>
-    """
-        + title
-        + """
-    </title>
+    <html>
+    <head>
+    <title>{title}</title>
     <!-- needed for adaptive design -->
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
-    <link rel="shortcut icon" href="https://fastapi.tiangolo.com/img/favicon.png">
-
+    <link rel="shortcut icon" href="{redoc_favicon_url}">
     <!--
     ReDoc doesn't change outer page styles
     -->
     <style>
-      body {
+      body {{
         margin: 0;
         padding: 0;
-      }
+      }}
     </style>
-  </head>
-  <body>
-    <redoc spec-url='"""
-        + openapi_url
-        + """'></redoc>
-    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
-  </body>
-</html>
+    </head>
+    <body>
+    <redoc spec-url="{openapi_url}"></redoc>
+    <script src="{redoc_js_url}"> </script>
+    </body>
+    </html>
     """
-    )
+    return HTMLResponse(html)
+
+
+def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse:
+    html = """
+    <!doctype html>
+    <html lang="en-US">
+    <body onload="run()">
+    </body>
+    </html>
+    <script>
+        'use strict';
+        function run () {
+            var oauth2 = window.opener.swaggerUIRedirectOauth2;
+            var sentState = oauth2.state;
+            var redirectUrl = oauth2.redirectUrl;
+            var isValid, qp, arr;
+
+            if (/code|token|error/.test(window.location.hash)) {
+                qp = window.location.hash.substring(1);
+            } else {
+                qp = location.search.substring(1);
+            }
+
+            arr = qp.split("&")
+            arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';})
+            qp = qp ? JSON.parse('{' + arr.join() + '}',
+                    function (key, value) {
+                        return key === "" ? value : decodeURIComponent(value)
+                    }
+            ) : {}
+
+            isValid = qp.state === sentState
+
+            if ((
+            oauth2.auth.schema.get("flow") === "accessCode"||
+            oauth2.auth.schema.get("flow") === "authorizationCode"
+            ) && !oauth2.auth.code) {
+                if (!isValid) {
+                    oauth2.errCb({
+                        authId: oauth2.auth.name,
+                        source: "auth",
+                        level: "warning",
+                        message: "Authorization may be unsafe, passed state was changed in server Passed state wasn't returned from auth server"
+                    });
+                }
+
+                if (qp.code) {
+                    delete oauth2.state;
+                    oauth2.auth.code = qp.code;
+                    oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
+                } else {
+                    let oauthErrorMsg
+                    if (qp.error) {
+                        oauthErrorMsg = "["+qp.error+"]: " +
+                            (qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
+                            (qp.error_uri ? "More info: "+qp.error_uri : "");
+                    }
+
+                    oauth2.errCb({
+                        authId: oauth2.auth.name,
+                        source: "auth",
+                        level: "error",
+                        message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server"
+                    });
+                }
+            } else {
+                oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
+            }
+            window.close();
+        }
+    </script>
+        """
+    return HTMLResponse(content=html)

fastapi/routing.py

@@ -1,6 +1,7 @@
 import asyncio
 import inspect
 import logging
+import re
 from typing import Any, Callable, Dict, List, Optional, Type, Union
 
 from fastapi import params
@@ -21,8 +22,14 @@ from starlette.concurrency import run_in_threadpool
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
-from starlette.routing import compile_path, get_name, request_response
-from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY
+from starlette.routing import (
+    compile_path,
+    get_name,
+    request_response,
+    websocket_session,
+)
+from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY, WS_1008_POLICY_VIOLATION
+from starlette.websockets import WebSocket
 
 
 def serialize_response(*, field: Field = None, response: Response) -> Any:
@@ -97,6 +104,35 @@ def get_app(
     return app
 
 
+def get_websocket_app(dependant: Dependant) -> Callable:
+    async def app(websocket: WebSocket) -> None:
+        values, errors, _ = await solve_dependencies(
+            request=websocket, dependant=dependant
+        )
+        if errors:
+            await websocket.close(code=WS_1008_POLICY_VIOLATION)
+            errors_out = ValidationError(errors)
+            raise HTTPException(
+                status_code=HTTP_422_UNPROCESSABLE_ENTITY, detail=errors_out.errors()
+            )
+        assert dependant.call is not None, "dependant.call must me a function"
+        await dependant.call(**values)
+
+    return app
+
+
+class APIWebSocketRoute(routing.WebSocketRoute):
+    def __init__(self, path: str, endpoint: Callable, *, name: str = None) -> None:
+        self.path = path
+        self.endpoint = endpoint
+        self.name = get_name(endpoint) if name is None else name
+        self.dependant = get_dependant(path=path, call=self.endpoint)
+        self.app = websocket_session(get_websocket_app(dependant=self.dependant))
+        regex = "^" + path + "$"
+        regex = re.sub("{([a-zA-Z_][a-zA-Z0-9_]*)}", r"(?P<\1>[^/]+)", regex)
+        self.path_regex, self.path_format, self.param_convertors = compile_path(path)
+
+
 class APIRoute(routing.Route):
     def __init__(
         self,
@@ -281,6 +317,19 @@ class APIRouter(routing.Router):
 
         return decorator
 
+    def add_api_websocket_route(
+        self, path: str, endpoint: Callable, name: str = None
+    ) -> None:
+        route = APIWebSocketRoute(path, endpoint=endpoint, name=name)
+        self.routes.append(route)
+
+    def websocket(self, path: str, name: str = None) -> Callable:
+        def decorator(func: Callable) -> Callable:
+            self.add_api_websocket_route(path, func, name=name)
+            return func
+
+        return decorator
+
     def include_router(
         self,
         router: "APIRouter",
@@ -326,6 +375,10 @@ class APIRouter(routing.Router):
                     include_in_schema=route.include_in_schema,
                     name=route.name,
                 )
+            elif isinstance(route, APIWebSocketRoute):
+                self.add_api_websocket_route(
+                    prefix + route.path, route.endpoint, name=route.name
+                )
             elif isinstance(route, routing.WebSocketRoute):
                 self.add_websocket_route(
                     prefix + route.path, route.endpoint, name=route.name

pyproject.toml

@@ -19,8 +19,8 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
 ]
 requires = [
-    "starlette ==0.11.1",
-    "pydantic >=0.17,<=0.25.0"
+    "starlette >=0.11.1,<=0.12.0",
+    "pydantic >=0.17,<=0.26.0"
 ]
 description-file = "README.md"
 requires-python = ">=3.6"

tests/test_application.py

@@ -1131,6 +1131,17 @@ def test_swagger_ui():
     assert response.status_code == 200
     assert response.headers["content-type"] == "text/html; charset=utf-8"
     assert "swagger-ui-dist" in response.text
+    assert (
+        f"oauth2RedirectUrl: window.location.origin + '/docs/oauth2-redirect'"
+        in response.text
+    )
+
+
+def test_swagger_ui_oauth2_redirect():
+    response = client.get("/docs/oauth2-redirect")
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "text/html; charset=utf-8"
+    assert "window.opener.swaggerUIRedirectOauth2" in response.text
 
 
 def test_redoc():

tests/test_custom_swagger_ui_redirect.py

@@ -0,0 +1,38 @@
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+swagger_ui_oauth2_redirect_url = "/docs/redirect"
+
+app = FastAPI(swagger_ui_oauth2_redirect_url=swagger_ui_oauth2_redirect_url)
+
+
+@app.get("/items/")
+async def read_items():
+    return {"id": "foo"}
+
+
+client = TestClient(app)
+
+
+def test_swagger_ui():
+    response = client.get("/docs")
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "text/html; charset=utf-8"
+    assert "swagger-ui-dist" in response.text
+    print(client.base_url)
+    assert (
+        f"oauth2RedirectUrl: window.location.origin + '{swagger_ui_oauth2_redirect_url}'"
+        in response.text
+    )
+
+
+def test_swagger_ui_oauth2_redirect():
+    response = client.get(swagger_ui_oauth2_redirect_url)
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "text/html; charset=utf-8"
+    assert "window.opener.swaggerUIRedirectOauth2" in response.text
+
+
+def test_response():
+    response = client.get("/items/")
+    assert response.json() == {"id": "foo"}

tests/test_local_docs.py

@@ -0,0 +1,56 @@
+import inspect
+
+from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+
+
+def test_strings_in_generated_swagger():
+    sig = inspect.signature(get_swagger_ui_html)
+    swagger_js_url = sig.parameters.get("swagger_js_url").default
+    swagger_css_url = sig.parameters.get("swagger_css_url").default
+    swagger_favicon_url = sig.parameters.get("swagger_favicon_url").default
+    html = get_swagger_ui_html(openapi_url="/docs", title="title")
+    body_content = html.body.decode()
+    assert swagger_js_url in body_content
+    assert swagger_css_url in body_content
+    assert swagger_favicon_url in body_content
+
+
+def test_strings_in_custom_swagger():
+    swagger_js_url = "swagger_fake_file.js"
+    swagger_css_url = "swagger_fake_file.css"
+    swagger_favicon_url = "swagger_fake_file.png"
+    html = get_swagger_ui_html(
+        openapi_url="/docs",
+        title="title",
+        swagger_js_url=swagger_js_url,
+        swagger_css_url=swagger_css_url,
+        swagger_favicon_url=swagger_favicon_url,
+    )
+    body_content = html.body.decode()
+    assert swagger_js_url in body_content
+    assert swagger_css_url in body_content
+    assert swagger_favicon_url in body_content
+
+
+def test_strings_in_generated_redoc():
+    sig = inspect.signature(get_redoc_html)
+    redoc_js_url = sig.parameters.get("redoc_js_url").default
+    redoc_favicon_url = sig.parameters.get("redoc_favicon_url").default
+    html = get_redoc_html(openapi_url="/docs", title="title")
+    body_content = html.body.decode()
+    assert redoc_js_url in body_content
+    assert redoc_favicon_url in body_content
+
+
+def test_strings_in_custom_redoc():
+    redoc_js_url = "fake_redoc_file.js"
+    redoc_favicon_url = "fake_redoc_file.png"
+    html = get_redoc_html(
+        openapi_url="/docs",
+        title="title",
+        redoc_js_url=redoc_js_url,
+        redoc_favicon_url=redoc_favicon_url,
+    )
+    body_content = html.body.decode()
+    assert redoc_js_url in body_content
+    assert redoc_favicon_url in body_content

tests/test_no_swagger_ui_redirect.py

@@ -0,0 +1,31 @@
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+app = FastAPI(swagger_ui_oauth2_redirect_url=None)
+
+
+@app.get("/items/")
+async def read_items():
+    return {"id": "foo"}
+
+
+client = TestClient(app)
+
+
+def test_swagger_ui():
+    response = client.get("/docs")
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "text/html; charset=utf-8"
+    assert "swagger-ui-dist" in response.text
+    print(client.base_url)
+    assert "oauth2RedirectUrl" not in response.text
+
+
+def test_swagger_ui_no_oauth2_redirect():
+    response = client.get("/docs/oauth2-redirect")
+    assert response.status_code == 404
+
+
+def test_response():
+    response = client.get("/items/")
+    assert response.json() == {"id": "foo"}

tests/test_tutorial/test_websockets/test_tutorial001.py

@@ -0,0 +1,25 @@
+import pytest
+from starlette.testclient import TestClient
+from starlette.websockets import WebSocketDisconnect
+from websockets.tutorial001 import app
+
+client = TestClient(app)
+
+
+def test_main():
+    response = client.get("/")
+    assert response.status_code == 200
+    assert b"<!DOCTYPE html>" in response.content
+
+
+def test_websocket():
+    with pytest.raises(WebSocketDisconnect):
+        with client.websocket_connect("/ws") as websocket:
+            message = "Message one"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}"
+            message = "Message two"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}"

tests/test_tutorial/test_websockets/test_tutorial002.py

@@ -0,0 +1,83 @@
+import pytest
+from starlette.testclient import TestClient
+from starlette.websockets import WebSocketDisconnect
+from websockets.tutorial002 import app
+
+client = TestClient(app)
+
+
+def test_main():
+    response = client.get("/")
+    assert response.status_code == 200
+    assert b"<!DOCTYPE html>" in response.content
+
+
+def test_websocket_with_cookie():
+    with pytest.raises(WebSocketDisconnect):
+        with client.websocket_connect(
+            "/items/1/ws", cookies={"session": "fakesession"}
+        ) as websocket:
+            message = "Message one"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == "Session Cookie or X-Client Header value is: fakesession"
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}, for item ID: 1"
+            message = "Message two"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == "Session Cookie or X-Client Header value is: fakesession"
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}, for item ID: 1"
+
+
+def test_websocket_with_header():
+    with pytest.raises(WebSocketDisconnect):
+        with client.websocket_connect(
+            "/items/2/ws", headers={"X-Client": "xmen"}
+        ) as websocket:
+            message = "Message one"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == "Session Cookie or X-Client Header value is: xmen"
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}, for item ID: 2"
+            message = "Message two"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == "Session Cookie or X-Client Header value is: xmen"
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}, for item ID: 2"
+
+
+def test_websocket_with_header_and_query():
+    with pytest.raises(WebSocketDisconnect):
+        with client.websocket_connect(
+            "/items/2/ws?q=baz", headers={"X-Client": "xmen"}
+        ) as websocket:
+            message = "Message one"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == "Session Cookie or X-Client Header value is: xmen"
+            data = websocket.receive_text()
+            assert data == "Query parameter q is: baz"
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}, for item ID: 2"
+            message = "Message two"
+            websocket.send_text(message)
+            data = websocket.receive_text()
+            assert data == "Session Cookie or X-Client Header value is: xmen"
+            data = websocket.receive_text()
+            assert data == "Query parameter q is: baz"
+            data = websocket.receive_text()
+            assert data == f"Message text was: {message}, for item ID: 2"
+
+
+def test_websocket_no_credentials():
+    with pytest.raises(WebSocketDisconnect):
+        client.websocket_connect("/items/2/ws")
+
+
+def test_websocket_invalid_data():
+    with pytest.raises(WebSocketDisconnect):
+        client.websocket_connect("/items/foo/ws", headers={"X-Client": "xmen"})

tests/test_ws_router.py

@@ -28,6 +28,13 @@ async def routerprefixindex(websocket: WebSocket):
     await websocket.close()
 
 
+@router.websocket("/router2")
+async def routerindex(websocket: WebSocket):
+    await websocket.accept()
+    await websocket.send_text("Hello, router!")
+    await websocket.close()
+
+
 app.include_router(router)
 app.include_router(prefix_router, prefix="/prefix")
 
@@ -51,3 +58,10 @@ def test_prefix_router():
     with client.websocket_connect("/prefix/") as websocket:
         data = websocket.receive_text()
         assert data == "Hello, router with prefix!"
+
+
+def test_router2():
+    client = TestClient(app)
+    with client.websocket_connect("/router2") as websocket:
+        data = websocket.receive_text()
+        assert data == "Hello, router!"