fastapi-voyager 0.12.1

Visualize FastAPI application's routing tree and dependencies

This repo is still in early stage, it supports pydantic v2 only

Visualize your FastAPI endpoints, and explore them interactively.

visit online demo of project: composition oriented development pattern

Installation

pip install fastapi-voyager
# or
uv add fastapi-voyager

voyager -m path.to.your.app.module --server

Sub-Application mounts are not supported yet, but you can specify the name of the FastAPI application used with --app. Only a single application (default: 'app') can be selected, but in a scenario where api is attached through app.mount("/api", api), you can select api like this:

voyager -m path.to.your.app.module --server --app api

Mount into project

from fastapi import FastAPI
from fastapi_voyager import create_voyager
from tests.demo import app

app.mount('/voyager', create_voyager(
    app, 
    module_color={"tests.service": "red"}, 
    module_prefix="tests.service"),
    swagger_url="/docs")

Features

For scenarios of using FastAPI as internal API integration endpoints, fastapi-voyager helps to visualize the dependencies.

It is also an architecture inspection tool that can identify issues in data relationships during design phase before turly implemtatioin.

If the process of building the view model follows the ER model, the full potential of fastapi-voyager can be realized. It allows for quick identification of APIs that use entities, as well as which entities are used by a specific API

highlight nodes and links

click a node to highlight it's upperstream and downstream nodes. figure out the related models of one page, or homw many pages are related with one model.

focus on nodes

Double click a node, and then toggle focus to hide irrelevant nodes.

view source code

double click a node or route to show source code or open file in vscode.

Command Line Usage

open in browser

# open in browser
voyager -m tests.demo --server  

voyager -m tests.demo --server --port=8002

generate the dot file

# generate .dot file
voyager -m tests.demo  

voyager -m tests.demo --app my_app

voyager -m tests.demo --schema Task

voyager -m tests.demo --show_fields all

voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato

voyager -m tests.demo -o my_visualization.dot

voyager --version

voyager --help

About pydantic-resolve

pydantic-resolve's @ensure_subset decorator helps safely pick fields from the 'source class' while indicating the reference from the current class to the base class.

pydantic-resolve is a lightweight tool designed to build complex, nested data in a simple, declarative way. In version 2.0.0alpha, it will introduce an important feature: ER Diagram, and fastapi-voyager will support this feature, allowing for a clearer understanding of the business relationships between the data.

Developers can use fastapi-voyager without needing to know anything about pydantic-resolve, but I still highly recommend everyone to give it a try.

Dependencies

• FastAPI
• pydantic-resolve
• Quasar

Credits

• https://apis.guru/graphql-voyager/, thanks for inspiration.
• https://github.com/tintinweb/vscode-interactive-graphviz, thanks for web visualization.

How to develop & contribute?

fork, clone.

install uv.

uv venv
source .venv/bin/activate
uv pip install ".[dev]"
uvicorn tests.programatic:app  --reload

open localhost:8000/voyager

frontend:

• src/web/vue-main.js: main js

backend:

• voyager.py: main entry
• render.py: generate dot file
• server.py: serve mode

Plan & Raodmap

• ideas
• changelog & roadmap