# fastapi-voyager **Repository Path**: joelive/fastapi-voyager ## Basic Information - **Project Name**: fastapi-voyager - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-17 - **Last Updated**: 2025-12-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README [![pypi](https://img.shields.io/pypi/v/fastapi-voyager.svg)](https://pypi.python.org/pypi/fastapi-voyager) ![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-voyager) [![PyPI Downloads](https://static.pepy.tech/badge/fastapi-voyager/month)](https://pepy.tech/projects/fastapi-voyager) Visualize your FastAPI endpoints, and explore them interactively. > This repo is still in early stage, it supports pydantic v2 only visit [live demo](https://www.newsyeah.fun/voyager/) source code:[composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern) image with simple configuration it can be embedded into FastAPI. ```python app.mount('/voyager', create_voyager( app, module_color={'src.services': 'tomato'}, module_prefix='src.services', swagger_url="/docs", ga_id="G-XXXXXXXXVL", initial_page_policy='first', online_repo_url='https://github.com/allmonday/composition-oriented-development-pattern/blob/master')) ``` https://github.com/allmonday/composition-oriented-development-pattern/blob/master/src/main.py#L48 ## Plan & Raodmap - [ideas](./docs/idea.md) - [changelog & roadmap](./docs/changelog.md) ## Installation ```bash pip install fastapi-voyager # or uv add fastapi-voyager ``` run with cli: ```shell voyager -m path.to.your.app.module --server ``` > [Sub-Application mounts](https://fastapi.tiangolo.com/advanced/sub-applications/) 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: ```shell voyager -m path.to.your.app.module --server --app api ``` ## Features For scenarios of using FastAPI as internal API integration endpoints, `fastapi-voyager` helps to visualize the dependencies. It is also an architecture tool that can identify issues inside implementation, finding out wrong relationships, overfetchs, or anything else. **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 Given ErDiagram defined by pydantic-resolve, application level entity relationship diagram can be visualized too. ### 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. image ### view source code double click a node or route to show source code or open file in vscode. image ### quick search seach schemas by name and dispaly it's upstream and downstreams. shift + click can quickly search current one image ### display ER diagram ER diagram is a new feature from pydantic-resolve which provide a solid expression for business descritpions. ```python diagram = ErDiagram( configs=[ Entity( kls=Team, relationships=[ Relationship( field='id', target_kls=list[Sprint], loader=sprint_loader.team_to_sprint_loader), Relationship( field='id', target_kls=list[User], loader=user_loader.team_to_user_loader) ] ), Entity( kls=Sprint, relationships=[ Relationship( field='id', target_kls=list[Story], loader=story_loader.sprint_to_story_loader) ] ), Entity( kls=Story, relationships=[ Relationship( field='id', target_kls=list[Task], loader=task_loader.story_to_task_loader), Relationship( field='owner_id', target_kls=User, loader=user_loader.user_batch_loader) ] ), Entity( kls=Task, relationships=[ Relationship( field='owner_id', target_kls=User, loader=user_loader.user_batch_loader) ] ) ] ) # display in voyager app.mount('/voyager', create_voyager( app, er_diagram=diagram) ``` image ## Command Line Usage ### open in browser ```bash # open in browser voyager -m tests.demo --server voyager -m tests.demo --server --port=8002 ``` ### generate the dot file ```bash # 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](https://github.com/allmonday/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. ```shell 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