fastapi-struct 0.1.1

CLI tool to generate standard, production-ready, modular folder structures for FastAPI applications in seconds.

---

Source Code: https://github.com/fastapi/fastapi
FastAPI Documentation: https://fastapi.tiangolo.com
PyPI Package: https://pypi.org/project/fastapi-struct/

---

⚡ What is fastapi-struct?

When starting a new FastAPI project, developers often spend hours configuring boilerplate: creating router files, structuring Pydantic schemas, setting up database sessions, writing .env configurations, and setting up pytest.

fastapi-struct gives you an instant, production-tested architectural foundation modeled after enterprise best practices—with a single command:

fastapi-struct my-api

Or scaffold directly inside your existing directory:

fastapi-struct .

---

🎯 Key Features

• ⚡ Fast to Scaffold: Spin up a complete, working FastAPI application in under 2 seconds.
• 🏛️ Enterprise Clean Architecture: Separation of concerns dividing Routers, Schemas, Database Models, Services, and Dependencies.
• 🛡️ Pydantic v2 & Settings: Preconfigured with pydantic-settings to safely read environment variables from .env.
• 🧪 Ready-to-Run Testing: Complete with pytest and httpx integration tests verifying / and /health.
• 📖 Interactive API Documentation: Instant Swagger UI (/docs) and ReDoc (/redoc) right out of the box.
• 🪶 Ultra Lightweight: Zero heavy runtime overhead; purely generates standard Python code.
• 💻 Cross-Platform: Works seamlessly on Windows PowerShell, CMD, macOS, and Linux.

---

📦 Installation & Quick Start

Option 1: Instant with uvx (No installation required)

Run it on-demand just like npx create-react-app:

uvx fastapi-struct my-api

Or in the current folder:

uvx fastapi-struct .

---

Option 2: Standard install with pip

pip install fastapi-struct

Generate your project:

fastapi-struct my-api

(Alias command create-fastapi-app my-api is also included!)

---

📂 The Generated Architecture

Every generated application follows a clean, decoupled layout:

my-api/
│
├── .env.example              # Sample environment variables
├── .gitignore                # Production Python/venv gitignore rules
├── pyproject.toml            # Project dependencies and Pytest configuration
├── README.md                 # Quickstart guide for your new API
│
├── app/
│   ├── __init__.py
│   ├── main.py               # Application factory & router registration
│   ├── dependencies.py       # Shared dependencies (Auth, DB session, etc.)
│   │
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py         # App configuration & BaseSettings (.env loader)
│   │
│   ├── routers/              # API endpoints organized by domain
│   │   ├── __init__.py
│   │   ├── health.py         # System health check (/health)
│   │   └── users.py          # Sample CRUD user endpoints
│   │
│   ├── schemas/              # Pydantic data validation & serialization
│   │   ├── __init__.py
│   │   └── user.py           # UserCreate & UserResponse models
│   │
│   ├── models/               # ORM & Database models (SQLAlchemy / SQLModel)
│   │   └── __init__.py
│   │
│   ├── services/             # Pure business logic layer
│   │   └── __init__.py
│   │
│   └── db/                   # Database engine & session management
│       ├── __init__.py
│       └── database.py
│
└── tests/                    # Automated testing suite
    ├── __init__.py
    └── test_main.py          # Pytest integration tests using TestClient

---

🚀 Running Your Generated Application

1. Step into your project directory

cd my-api

(Skip if generated with fastapi-struct .)

2. Create and activate a virtual environment

On Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

On Windows (Command Prompt):

python -m venv .venv
call .venv\Scripts\activate.bat

On macOS & Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies in editable mode

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

4. Start the development server

python -m uvicorn app.main:app --reload

---

🔍 Explore Your API

Once your server is running:

Service	URL	Description
Root Endpoint	http://127.0.0.1:8000/	Welcome JSON response
Health Check	http://127.0.0.1:8000/health	Uptime monitoring endpoint
Interactive Docs (Swagger UI)	http://127.0.0.1:8000/docs	Test endpoints directly in browser
Alternative Docs (ReDoc)	http://127.0.0.1:8000/redoc	Clean API reference docs

---

🧪 Running Automated Tests

Run the included Pytest suite with:

python -m pytest

Output:

tests\test_main.py ..                                                    [100%]
============================== 2 passed in 0.45s ==============================

---

🧩 Adding a New Feature

Adding new capabilities to your generated app takes just 3 clean steps:

1. Define your Pydantic Schema (app/schemas/item.py)

from pydantic import BaseModel, Field

class ItemCreate(BaseModel):
    title: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)

class ItemResponse(ItemCreate):
    id: int

2. Create your Router (app/routers/items.py)

from fastapi import APIRouter
from app.schemas.item import ItemCreate, ItemResponse

router = APIRouter(prefix="/items", tags=["Items"])

@router.post("/", response_model=ItemResponse)
async def create_item(item: ItemCreate):
    return {"id": 1, **item.model_dump()}

3. Register in app/main.py

from app.routers.items import router as items_router

app.include_router(items_router)

The server automatically reloads, and the new /items endpoint is instantly testable at http://127.0.0.1:8000/docs!

---

📜 License

This project is open-source software licensed under the MIT License.