Voyager Visualization

中文版

This page solves one problem: your FastAPI app has dozens of endpoints and Pydantic schemas, and you need a visual map to understand how they connect — without reading source files one by one.

Goal

You have this:

app = FastAPI()

@app.get("/tasks", response_model=list[TaskView])
async def get_tasks(): ...

@app.get("/sprints/{sprint_id}", response_model=SprintView)
async def get_sprint(sprint_id: int): ...

You want this — an interactive graph where you can click any endpoint or schema and immediately see its dependencies:

┌─────────────┐     ┌──────────┐     ┌──────────┐
│ GET /tasks  │────▶│ TaskView │────▶│ UserView │
└─────────────┘     └──────────┘     └──────────┘
┌──────────────────┐     ┌────────────┐
│ GET /sprints/:id │────▶│ SprintView │
└──────────────────┘     └────────────┘

fastapi-voyager renders your endpoints, schemas, and entity relationships as a navigable graph. When used with pydantic-resolve's ER Diagram, it also displays entity-level relationship diagrams.

Install

pip install fastapi-voyager

Step 1: Mount Voyager

Add one line to your FastAPI app:

from fastapi import FastAPI
from fastapi_voyager import create_voyager

app = FastAPI()

app.mount('/voyager', create_voyager(app))  # (1)

1. Open /voyager in your browser to see the interactive graph of all endpoints and their dependencies.

Step 2: Add ER Diagram

When you have an ErDiagram from pydantic-resolve, pass it to visualize entity relationships alongside your API structure:

from pydantic_resolve import ErDiagram, Entity, Relationship

diagram = ErDiagram(  # (1)
    entities=[
        Entity(
            kls=SprintEntity,
            relationships=[
                Relationship(fk='id', target=list[TaskEntity], name='tasks', loader=task_loader),
            ],
        ),
        Entity(
            kls=TaskEntity,
            relationships=[
                Relationship(fk='owner_id', target=UserEntity, name='owner', loader=user_loader),
            ],
        ),
    ],
)

app.mount('/voyager', create_voyager(app, er_diagram=diagram))  # (2)

1. Define the same ErDiagram you use for AutoLoad and GraphQL.
2. Voyager renders a combined view: API endpoints and their underlying entity relationships. Open /voyager and switch to the ER Diagram tab to explore.

Step 3: Configure Options

create_voyager accepts optional parameters to customize the visualization:

app.mount(
    '/voyager',
    create_voyager(
        app,
        module_color={'src.services': 'tomato'},      # (1)
        module_prefix='src.services',                   # (2)
        swagger_url="/docs",                            # (3)
        initial_page_policy='first',                    # (4)
        online_repo_url='https://github.com/example/my-project/blob/main',  # (5)
        enable_pydantic_resolve_meta=True,              # (6)
    ),
)

1. module_color — map module paths to highlight colors.
2. module_prefix — filter to only show routes under this prefix.
3. swagger_url — link to your Swagger docs.
4. initial_page_policy — which page to show first: 'first' or 'all'.
5. online_repo_url — base URL for linking nodes to source code in your repository.
6. enable_pydantic_resolve_meta — show resolve_* and post_* annotations on each schema.

Interactive Features

Highlight Dependencies

Click any node to highlight its upstream and downstream dependencies. See which models an endpoint uses, or which endpoints depend on a specific model.

View Source Code

Double-click a node or route to view its source code. If online_repo_url is configured, it can also open the file directly in VS Code.

Quick Search

Search schemas by name and display their upstream and downstream relationships. Shift+click on a node to search for it immediately.

pydantic-resolve Meta

When enable_pydantic_resolve_meta=True, toggle the "pydantic resolve meta" view to see resolve_* and post_* annotations on each schema — useful for understanding the data assembly logic at a glance.

Command Line Usage

Generate visualizations without running a server:

# Open in browser
voyager -m path.to.your.app.module --server

# Custom port
voyager -m path.to.your.app.module --server --port=8002

# Generate .dot file
voyager -m path.to.your.app.module

# Filter by schema name
voyager -m path.to.your.app.module --schema Task

# Show all fields
voyager -m path.to.your.app.module --show_fields all

# Custom module colors
voyager -m path.to.your.app.module --module_color=tests.demo:red --module_color=tests.service:tomato

# Output to file
voyager -m path.to.your.app.module -o my_visualization.dot

# Select a specific FastAPI app (for mounted sub-applications)
voyager -m path.to.your.app.module --server --app api

Live Demo

• Online Demo — Interactive Voyager visualization.
• GraphQL Demo — GraphQL endpoint powered by pydantic-resolve.