S Smits Fastapi Doctor Fastapi Doctor

FastAPI Doctor

Opinionated backend health checker for FastAPI applications. Scores the backend 0-100 using severity-weighted unique rule violations across 7 categories. All checks use AST-based static analysis — no regex hacks. Configurable via .fastapi-doctor.yml in your project root.

When applying findings, prefer the smallest semantic diff that resolves the rule. Do not introduce style-only rewrites such as replacing imported helpers with module-qualified calls unless the finding explicitly requires that change.

Configuration

Place .fastapi-doctor.yml in your project root. All keys are optional — missing keys use defaults. See .fastapi-doctor.example.yml for the full schema.

architecture:
  enabled: true           # false → skip ALL architecture rules (defer to ruff)
  giant_function: 400     # 0 → disable specific rule
  large_function: 200
  god_module: 1500
  deep_nesting: 5
  import_bloat: 30
  fat_route_handler: 100

pydantic:
  should_be_model: "boundary"  # or "everywhere"

api:
  create_post_prefixes: []     # optional route prefixes for POST->201 heuristic
  tag_required_prefixes:       # prefixes that should carry OpenAPI tags
    - "/api/"

security:
  forbidden_write_params: []   # optional param names to ban on write routes

scan:
  include_tests: false
  tool_include_dirs: []
  tool_exclude_dirs:
    - tests

Scoring Formula

score = 100 - (unique_error_rules × 2.0 + unique_warning_rules × 1.0)

Counts unique rule types violated, not instances. 60 dataclass violations count as 1 warning penalty (1 point).

Score bands:

• 80-100 (Great): Ship it
• 60-79 (Needs work): Fix before merge
• Below 60 (Critical): Stop and fix

Categories

Sophisticated Checks

pydantic/should-be-model — Configurable Pydantic adoption detector

Two modes via .fastapi-doctor.yml → pydantic.should_be_model:

"boundary" (default) — Trust-boundary analysis. Only flags at API edges (routers, interfaces, schemas) or with API-suggestive names (*Request, *Response, *Schema, *Payload, *Body, *Input, *Output). Internal code is free to use dataclasses and TypedDicts.

"everywhere" — Consistency-first. Flags ALL TypedDict/NamedTuple/dataclass. Some teams prefer Pydantic everywhere for uniform serialization and fewer mental-model switches. Both approaches are valid.

Both modes exempt: @dataclass(slots=True), @dataclass(frozen=True), TypedDict(total=False) (PATCH pattern), small NamedTuples (≤3 fields), TYPE_CHECKING blocks.

resilience/reraise-without-context — AST-based noise detector

Finds except handlers that catch and immediately re-raise without adding ANY value (no logging, no cleanup, no wrapping). These try/except blocks are pure noise — remove them or add context with raise NewError(...) from exc.

architecture/passthrough-function — AST-based abstraction detector

Finds functions whose body is a single return other_func(same_args) — unnecessary indirection. Smart exemptions: decorated functions, methods, validators, functions with docstrings, <2 params.

architecture/import-bloat — AST-based module complexity signal

Files with >30 import statements depend on too many things. Use TYPE_CHECKING guards, lazy imports, or split the module. Exempts: __init__.py, main.py. Threshold configurable via .fastapi-doctor.yml.

Commands

Ask the user which profile they want before running it: security, balanced, or strict.

Run from the target project's working directory, or pass --repo-root when scanning another checkout.

# Quick scan (doctor checks + ruff + ty)
uv run fastapi-doctor

# Full scan (add bandit + targeted tests)
uv run fastapi-doctor --with-tests --with-bandit

# Machine-readable output
uv run fastapi-doctor --json

# Scan a different repo explicitly
uv run fastapi-doctor --repo-root /path/to/project

If the target repo is still on Python 3.11 or older, install fastapi-doctor as a wheel-backed tool in an isolated Python 3.12+ env instead of adding it to the app environment:

uv tool install --python 3.12 --index https://s-smits.github.io/fastapi-doctor/simple/ fastapi-doctor

Common layout recipes:

repo/
  src/my_service/main.py

uv run fastapi-doctor --profile strict --repo-root . --app-module my_service.main:app

repo/
  apps/
    service_api/
      __init__.py
      main.py

uv run fastapi-doctor --profile strict --repo-root . --code-dir apps/service_api --import-root . --app-module apps.service_api.main:app

Rule Reference

Errors (2.0 point penalty per unique rule)

Warnings (1.0 point penalty per unique rule)

Rule intent notes:

• performance/sequential-awaits is for independent read-style awaits. Ordered lifecycle/write side effects such as cancel_*, persist_*, mark_*, clear_*, acquire_*, release_*, and invalidate_* are treated as intentionally sequential.
• architecture/fat-route-handler keeps read endpoints tight while allowing some extra scaffolding for POST/PUT/PATCH/DELETE handlers. Use a nearby doctor:ignore architecture/fat-route-handler reason="..." only when the route is intentionally deferred and has an owner. | config/env-mutation | Config | Service/router mutates process env outside bootstrap entrypoints | | resilience/exception-log-without-traceback | Resilience | Exception is logged without traceback context | | security/exception-detail-leak | Security | Exposing unhandled internal Exception messages to users | | security/exception-string-response | Security | Exposing str(exc) through response/event payloads | | security/insecure-cookie | Security | Cookie missing secure, httponly, or samesite | | correctness/naive-datetime | Correctness | Usage of datetime.utcnow() or now() without timezones | | correctness/avoid-os-path | Correctness | Usage of os.path APIs instead of pathlib.Path |

Thresholds (configurable via .fastapi-doctor.yml)

Set any threshold to 0 to disable that specific rule. Set architecture.enabled: false to disable all architecture rules (defer to ruff/pylint).

Source: s-smits/fastapi-doctor — distributed by TomeVault.