fastapi-voyager 0.11.11

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")

more about sub application

Feature

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 through visualization during the design phase.

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

git clone https://github.com/allmonday/fastapi-voyager.git
cd fastapi-voyager

voyager -m tests.demo 
           --server --port=8001 
           --module_color=tests.service:blue 
           --module_color=tests.demo:tomato

highlight

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

toggle focus to hide nodes not related with current picked one.

before: after:

view source code

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

double click a 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

The tool will generate a DOT file that you can render using Graphviz:

# Install graphviz
brew install graphviz  # macOS
apt-get install graphviz  # Ubuntu/Debian

# Render the graph
dot -Tpng router_viz.dot -o router_viz.png

# Or view online at: https://dreampuf.github.io/GraphvizOnline/

or you can open router_viz.dot with vscode extension graphviz interactive preview

Plan before v1.0

backlog

• user can generate nodes/edges manually and connect to generated ones
  • eg: add owner
  • add extra info for schema
• optimize static resource (allow manually config url)
• improve search dialog
  • add route/tag list
• type alias should not be kept as node instead of compiling to original type
• how to correctly handle the generic type ?
• support Google analysis config

in analysis

• click field to highlight links
• animation effect for edges
• display standard ER diagram spec. hard but important
  • display potential invalid links
  • highlight relationship belongs to ER diagram

plan:

<0.9:

• group schemas by module hierarchy
• module-based coloring via Analytics(module_color={...})
• view in web browser
  • config params
  • make a explorer dashboard, provide list of routes, schemas, to make it easy to switch and search
• support programmatic usage
• better schema /router node appearance
• hide fields duplicated with parent's (show parent fields instead)
• refactor the frontend to vue, and tweak the build process
• find dependency based on picked schema and it's field.
• optimize static resource (cdn -> local)
• add configuration for highlight (optional)
• alt+click to show field details
• display source code of routes (including response_model)
• handle excluded field
• add tooltips
• route
  • group routes by module hierarchy
  • add response_model in route
• fixed left bar show tag/ route
• export voyager core data into json (for better debugging)
  • add api to rebuild core data from json, and render it
• fix Generic case test_generic.py
• show tips for routes not return pydantic type.
• fix duplicated link from class and parent class, it also break clicking highlight
• refactor: abstract render module

0.9

• refactor: server.py
  • rename create_app_with_fastapi -> create_voyager
  • add doc for parameters
• improve initialization time cost
  • query route / schema info through realtime api
  • adjust fe
• 0.9.3
  • adjust layout
    • show field detail in right panel
    • show route info in bottom
• 0.9.4
  • close schema sidebar when switch tag/route
  • schema detail panel show fields by default
  • adjust schema panel's height
  • show from base information in subset case
• 0.9.5
  • route list should have a max height

0.10

• 0.10.1
  • refactor voyager.py tag -> route structure
  • fix missing route (tag has only one route which return primitive value)
  • make right panel resizable by dragging
  • allow closing tag expansion item
  • hide brief mode if not configured
  • add focus button to only show related nodes under current route/tag graph in dialog
• 0.10.2
  • fix graph height
  • show version in title
• 0.10.3
  • fix focus in brief-mode
  • ui: adjust focus position
  • refactor naming
  • fix layout issue when rendering huge graph
• 0.10.4
  • fix: when focus is on, should ensure changes from other params not broken.
• 0.10.5
  • double click to show details, and highlight as tomato

0.11

• 0.11.1
  • support opening route in swagger
    • config docs path
  • provide option to hide routes in brief mode (auto hide in full graph mode)
• 0.11.2
  • enable/disable module cluster (to save space)
• 0.11.3
  • support online repo url
• 0.11.4
  • add loading for field detail panel
• 0.11.5
  • optimize open in swagger link
  • change jquery cdn
• 0.11.6
  • flag of loading full graph in first render or not
  • optimize loading static resource
• 0.11.7
  • fix swagger link
• 0.11.8
  • fix swagger link in another way
• 0.11.9
  • replace issubclass with safe_issubclass to prevent exception.
• 0.11.10
  • fix bug during updating forward refs
• 0.11.11
  • replace print with logging and add --log-level in cli, by default info
  • fill node title color with module color
  • optimize cluster render logic

0.12

• 0.12.1
  • sort tag / route names in left panel
  • sort field name in nodes
  • set max limit for fields in nodes
  • upgrade network algorithm (optional)
  • refactor render.py

0.13

• 0.12.0
  • integration with pydantic-resolve
    • show hint for resolve, post fields
    • display loader as edges
  • add tests

0.13

placeholder

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, it will introduce an important feature: ER model definition, and fastapi-voyager will support and visualize these diagrams.

Developers can use fastapi-voyager without needing to know about pydantic-resolve.

Credits

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

Dependencies

• FastAPI
• pydantic-resolve
• Quasar

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 backend: voyager.py, render.py, server.py

Branch and Release flow

TODO