From 0ceefb3c886d1143ac9bb0389f2eaa3c5acc57e7 Mon Sep 17 00:00:00 2001
From: Den Kasyanov <den@den.ai>
Date: Fri, 30 Aug 2024 18:00:26 +0400
Subject: [PATCH] Update FastAPI integration docs (#6833) (#6850)

## Summary

- Fixed the directory structure and commands for the second scenario
#6833
- Added a headline "Migrating an existing FastAPI project" because the
first part looks like a migration scenario, but didn't have its own
section before.
- Added explicit `--app` flags to commands to emphasize that the
commands create an Application project. Although maybe unnecessary
considering that `--app` is now default.
- Added instructions for testing that the dev server and Docker image
work correctly
- Took the liberty of adding a `project` at the root of all directory
structures and appropriate commands.
- With explicitly defined root directory it is easier to differentiate
between the `project` root directory and FastAPI's `app` directory.
- Without it it could be less obvious for developers less familiar with
FastAPI. Had a similar issue when started using Django several years
ago.
- If I left `app` in the command, then after copying the **app
directory** from https://github.com/astral-sh/uv-fastapi-example the
path would be `app/app/...`.
- Cleaned up glyphs in tree sctructures that were copied from FastAPI
docs.

## Caveats

- On project initialization `hello.py` is created. It is not reflected
in directory structure trees in this PR and may be slightly confusing
for developers less familiar with uv.
- I believe it will be soon addressed in #6750 and after that the docs
will reflect actual directory structure.
---
 docs/guides/integration/fastapi.md | 79 +++++++++++++++++++-----------
 1 file changed, 51 insertions(+), 28 deletions(-)

diff --git a/docs/guides/integration/fastapi.md b/docs/guides/integration/fastapi.md
index 4fd923e51f19..c2d6aef3e5ca 100644
--- a/docs/guides/integration/fastapi.md
+++ b/docs/guides/integration/fastapi.md
@@ -8,32 +8,36 @@ environments, running FastAPI applications, and more.
 
     You can view the source code for this guide in the [uv-fastapi-example](https://github.com/astral-sh/uv-fastapi-example) repository.
 
+## Migrating an existing FastAPI project
+
 As an example, consider the sample application defined in the
 [FastAPI documentation](https://fastapi.tiangolo.com/tutorial/bigger-applications/), structured as
 follows:
 
 ```plaintext
-.
-├── app
-│   ├── __init__.py
-│   ├── main.py
-│   ├── dependencies.py
-│   └── routers
-│   │   ├── __init__.py
-│   │   ├── items.py
-│   │   └── users.py
-│   └── internal
-│       ├── __init__.py
-│       └── admin.py
+project
+└── app
+    ├── __init__.py
+    ├── main.py
+    ├── dependencies.py
+    ├── routers
+    │   ├── __init__.py
+    │   ├── items.py
+    │   └── users.py
+    └── internal
+        ├── __init__.py
+        └── admin.py
 ```
 
-To use uv with this project, add a `pyproject.toml` file to the root directory of the project with
-`uv init`:
+To use uv with this application, inside the `project` directory run:
 
 ```console
-$ uv init
+$ uv init --app
 ```
 
+This creates an [Application project](../../concepts/projects.md#applications) with a
+`pyproject.toml` file.
+
 Then, add a dependency on FastAPI:
 
 ```console
@@ -43,19 +47,19 @@ $ uv add fastapi --extra standard
 You should now have the following structure:
 
 ```plaintext
-.
+project
 ├── pyproject.toml
-├── app
-│   ├── __init__.py
-│   ├── main.py
-│   ├── dependencies.py
-│   └── routers
-│   │   ├── __init__.py
-│   │   ├── items.py
-│   │   └── users.py
-│   └── internal
-│       ├── __init__.py
-│       └── admin.py
+└── app
+    ├── __init__.py
+    ├── main.py
+    ├── dependencies.py
+    ├── routers
+    │   ├── __init__.py
+    │   ├── items.py
+    │   └── users.py
+    └── internal
+        ├── __init__.py
+        └── admin.py
 ```
 
 And the contents of the `pyproject.toml` file should look something like this:
@@ -82,6 +86,8 @@ $ uv run fastapi dev
 alongside the `pyproject.toml`), create a virtual environment, and run the command in that
 environment.
 
+Test the app by opening http://127.0.0.1:8000/?token=jessica in a web browser.
+
 ## Deployment
 
 To deploy the FastAPI application with Docker, you can use the following `Dockerfile`:
@@ -103,4 +109,21 @@ RUN uv sync --frozen --no-cache
 CMD ["/app/.venv/bin/fastapi", "run", "app/main.py", "--port", "80", "--host", "0.0.0.0"]
 ```
 
-For more on using uv with Docker, see the [Docker guide](./docker.md).
+Build the Docker image with:
+
+```console
+$ docker build -t fastapi-app .
+```
+
+Run the Docker container locally with:
+
+```console
+$ docker run -p 8000:80 fastapi-app
+```
+
+Navigate to http://127.0.0.1:8000/?token=jessica in your browser to verify that the app is running
+correctly.
+
+!!! tip
+
+    For more on using uv with Docker, see the [Docker guide](./docker.md).