| Name | fastapi-voyager JSON |
| Version |
0.8.3
JSON |
| download |
| home_page | None |
| Summary | Visualize FastAPI application's routing tree and dependencies |
| upload_time | 2025-10-19 13:11:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
fastapi
openapi
routing
visualization
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.python.org/pypi/fastapi-voyager)
<p align="center"><img src="./voyager.jpg" alt="" /></p>
> This repo is still in early stage, currently it supports pydantic v2 only, previous name: fastapi-router-viz
Inspect your API interactively
<img width="1480" height="648" alt="image" src="https://github.com/user-attachments/assets/a6ccc9f1-cf06-493a-b99b-eb07767564bd" />
## Installation
```bash
pip install fastapi-voyager
# or
uv add fastapi-voyager
```
```shell
voyager -m path.to.your.app.module --server
```
## Dependencies
- FastAPI
- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
## 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
```shell
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
```
### generate the graph
after initialization, pick tag, rotue (optional) and click `generate`.
<img width="1919" height="898" alt="image" style="border: 1px solid #aaa" src="https://github.com/user-attachments/assets/05e321d0-49f3-4af6-a7c7-f4c9c6b1dbfd" />
### 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.
<img width="1485" height="616" alt="image" style="border: 1px solid #aaa" src="https://github.com/user-attachments/assets/70c4095f-86c7-45da-a6f0-fd41ac645813" />
### filter related nodes
`shift` click a node to check related node, pick a field to narrow the result.
<img width="1917" height="800" alt="image" style="border: 1px solid #aaa" src="https://github.com/user-attachments/assets/e770dc70-f293-49e1-bcd7-d8dffa15d9ea" />
### view source code
`alt` click a node to show source code or open file in vscode.
<img width="1049" height="694" alt="image" src="https://github.com/user-attachments/assets/7839ac83-8d60-44ad-b1c9-9652a76339b1" />
<img width="1042" height="675" alt="image" src="https://github.com/user-attachments/assets/38ae705f-5982-4a02-9c3f-038b1d00bcf6" />
`alt` click a route to show source code or open file in vscode
<img width="882" height="445" alt="image" src="https://github.com/user-attachments/assets/158560ef-63ca-4991-9b7d-587be4fa04e4" />
## Mount to target project
```python
from fastapi import FastAPI
from fastapi_voyager.server import create_app_with_fastapi
from tests.demo import app
app.mount('/voyager', create_app_with_fastapi(
app,
module_color={"tests.service": "red"},
module_prefix="tests.service"))
```
more about [sub application](https://fastapi.tiangolo.com/advanced/sub-applications/?h=sub)
## 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
```
The tool will generate a DOT file that you can render using Graphviz:
```bash
# 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
features:
- [x] group schemas by module hierarchy
- [x] module-based coloring via Analytics(module_color={...})
- [x] view in web browser
- [x] config params
- [x] make a explorer dashboard, provide list of routes, schemas, to make it easy to switch and search
- [x] support programmatic usage
- [x] better schema /router node appearance
- [x] hide fields duplicated with parent's (show `parent fields` instead)
- [x] refactor the frontend to vue, and tweak the build process
- [x] find dependency based on picked schema and it's field.
- [x] optimize static resource (cdn -> local)
- [x] add configuration for highlight (optional)
- [x] alt+click to show field details
- [x] display source code of routes (including response_model)
- [x] handle excluded field
- [x] add tooltips
- [x] route
- [x] group routes by module hierarchy
- [ ] add response_model in route
- [ ] support dataclass (pending)
- [ ] click field to highlight links
- [ ] user can generate nodes/edges manually and connect to generated ones
- [ ] add owner
- [ ] add extra info for schema
- [ ] ui optimization
- [ ] fixed left/right bar show field information
- [x] fixed left bar show tag/ route
- [ ] display standard ER diagram `difference`
- [ ] display potential invalid links
- [ ] integration with pydantic-resolve
- [ ] show difference between resolve, post fields
- [x] strikethrough for excluded fields
- [ ] display loader as edges
- [x] export voyager core data into json (for better debugging)
- [x] add api to rebuild core data from json, and render it
- [x] fix Generic case `test_generic.py`
- [ ] show tips for routes not return pydantic type.
- [ ] add http method for route
bugs & non feature:
- [x] fix duplicated link from class and parent class, it also break clicking highlight
- [ ] add tests
- [x] refactor
- [x] abstract render module
## Using with pydantic-resolve
pydantic-resolve's @ensure_subset decorator is helpful to pick fields from `source class` in safe.
TODO: ...
## Credits
- https://apis.guru/graphql-voyager/, for inspiration.
- https://github.com/tintinweb/vscode-interactive-graphviz, for web visualization.
## Changelog
- 0.8:
- 0.8.2
- fix silly typo.
- 0.8.1
- add feature: hide primitive routes
- 0.7:
- 0.7.5
- fix show all display issue
- 0.7.4
- optimize tag/route, move to left.
- fresh on change, no need to click generate any more.
- 0.7.3
- fix `module_color` failure
- 0.7.2
- keep links inside filtered nodes.
- 0.7.1
- support brief mode, you can use `--module_prefix tests.service` to show links between routes and filtered schemas, to make the graph less complicated.
- 0.6:
- 0.6.2:
- fix generic related issue
Raw data
{
"_id": null,
"home_page": null,
"name": "fastapi-voyager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "fastapi, openapi, routing, visualization",
"author": null,
"author_email": "Tangkikodo <allmonday@126.com>",
"download_url": "https://files.pythonhosted.org/packages/95/74/0dcc21b6e23fd91cc32cce0aa2fed16ae5b6cfdab3d615113c300e4d8ae3/fastapi_voyager-0.8.3.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/fastapi-voyager)\n\n\n<p align=\"center\"><img src=\"./voyager.jpg\" alt=\"\" /></p>\n\n> This repo is still in early stage, currently it supports pydantic v2 only, previous name: fastapi-router-viz\n\nInspect your API interactively\n\n<img width=\"1480\" height=\"648\" alt=\"image\" src=\"https://github.com/user-attachments/assets/a6ccc9f1-cf06-493a-b99b-eb07767564bd\" />\n\n## Installation\n\n```bash\npip install fastapi-voyager\n# or\nuv add fastapi-voyager\n```\n\n```shell\nvoyager -m path.to.your.app.module --server\n```\n\n## Dependencies\n\n- FastAPI\n- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)\n\n\n## Feature\n\nFor scenarios of using FastAPI as internal API integration endpoints, `fastapi-voyager` helps to visualize the dependencies.\n\nIt is also an architecture inspection tool that can identify issues in data relationships through visualization during the design phase.\n\nIf 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\n\n\n\n```shell\ngit clone https://github.com/allmonday/fastapi-voyager.git\ncd fastapi-voyager\n\nvoyager -m tests.demo \n --server --port=8001 \n --module_color=tests.service:blue \n --module_color=tests.demo:tomato\n```\n\n### generate the graph\nafter initialization, pick tag, rotue (optional) and click `generate`.\n\n<img width=\"1919\" height=\"898\" alt=\"image\" style=\"border: 1px solid #aaa\" src=\"https://github.com/user-attachments/assets/05e321d0-49f3-4af6-a7c7-f4c9c6b1dbfd\" />\n\n### highlight\nclick 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.\n\n<img width=\"1485\" height=\"616\" alt=\"image\" style=\"border: 1px solid #aaa\" src=\"https://github.com/user-attachments/assets/70c4095f-86c7-45da-a6f0-fd41ac645813\" />\n\n### filter related nodes\n`shift` click a node to check related node, pick a field to narrow the result.\n\n<img width=\"1917\" height=\"800\" alt=\"image\" style=\"border: 1px solid #aaa\" src=\"https://github.com/user-attachments/assets/e770dc70-f293-49e1-bcd7-d8dffa15d9ea\" />\n\n### view source code\n`alt` click a node to show source code or open file in vscode.\n\n<img width=\"1049\" height=\"694\" alt=\"image\" src=\"https://github.com/user-attachments/assets/7839ac83-8d60-44ad-b1c9-9652a76339b1\" />\n\n<img width=\"1042\" height=\"675\" alt=\"image\" src=\"https://github.com/user-attachments/assets/38ae705f-5982-4a02-9c3f-038b1d00bcf6\" />\n\n`alt` click a route to show source code or open file in vscode\n\n<img width=\"882\" height=\"445\" alt=\"image\" src=\"https://github.com/user-attachments/assets/158560ef-63ca-4991-9b7d-587be4fa04e4\" />\n\n\n## Mount to target project\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_voyager.server import create_app_with_fastapi\nfrom tests.demo import app\n\napp.mount('/voyager', create_app_with_fastapi(\n app, \n module_color={\"tests.service\": \"red\"}, \n module_prefix=\"tests.service\"))\n```\n\nmore about [sub application](https://fastapi.tiangolo.com/advanced/sub-applications/?h=sub)\n\n\n## Command Line Usage\n\n### open in browser\n\n```bash\n# open in browser\nvoyager -m tests.demo --server \n\nvoyager -m tests.demo --server --port=8002\n```\n\n### generate the dot file\n```bash\n# generate .dot file\nvoyager -m tests.demo \n\nvoyager -m tests.demo --app my_app\n\nvoyager -m tests.demo --schema Task\n\nvoyager -m tests.demo --show_fields all\n\nvoyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato\n\nvoyager -m tests.demo -o my_visualization.dot\n\nvoyager --version\n```\n\nThe tool will generate a DOT file that you can render using Graphviz:\n\n```bash\n# Install graphviz\nbrew install graphviz # macOS\napt-get install graphviz # Ubuntu/Debian\n\n# Render the graph\ndot -Tpng router_viz.dot -o router_viz.png\n\n# Or view online at: https://dreampuf.github.io/GraphvizOnline/\n```\n\nor you can open router_viz.dot with vscode extension `graphviz interactive preview`\n\n\n## Plan before v1.0\n\nfeatures:\n- [x] group schemas by module hierarchy\n- [x] module-based coloring via Analytics(module_color={...})\n- [x] view in web browser\n - [x] config params\n - [x] make a explorer dashboard, provide list of routes, schemas, to make it easy to switch and search\n- [x] support programmatic usage\n- [x] better schema /router node appearance\n- [x] hide fields duplicated with parent's (show `parent fields` instead)\n- [x] refactor the frontend to vue, and tweak the build process\n- [x] find dependency based on picked schema and it's field.\n- [x] optimize static resource (cdn -> local)\n- [x] add configuration for highlight (optional)\n- [x] alt+click to show field details\n- [x] display source code of routes (including response_model)\n- [x] handle excluded field \n- [x] add tooltips\n- [x] route\n - [x] group routes by module hierarchy\n - [ ] add response_model in route\n- [ ] support dataclass (pending)\n- [ ] click field to highlight links\n- [ ] user can generate nodes/edges manually and connect to generated ones\n - [ ] add owner\n - [ ] add extra info for schema\n- [ ] ui optimization\n - [ ] fixed left/right bar show field information\n - [x] fixed left bar show tag/ route\n- [ ] display standard ER diagram `difference`\n - [ ] display potential invalid links\n- [ ] integration with pydantic-resolve\n - [ ] show difference between resolve, post fields\n - [x] strikethrough for excluded fields\n - [ ] display loader as edges\n- [x] export voyager core data into json (for better debugging)\n - [x] add api to rebuild core data from json, and render it\n- [x] fix Generic case `test_generic.py`\n- [ ] show tips for routes not return pydantic type.\n- [ ] add http method for route\n\nbugs & non feature:\n- [x] fix duplicated link from class and parent class, it also break clicking highlight\n- [ ] add tests\n- [x] refactor\n - [x] abstract render module\n\n## Using with pydantic-resolve\n\npydantic-resolve's @ensure_subset decorator is helpful to pick fields from `source class` in safe.\n\nTODO: ...\n\n\n## Credits\n\n- https://apis.guru/graphql-voyager/, for inspiration.\n- https://github.com/tintinweb/vscode-interactive-graphviz, for web visualization.\n\n\n## Changelog\n\n- 0.8:\n - 0.8.2\n - fix silly typo.\n - 0.8.1\n - add feature: hide primitive routes\n- 0.7:\n - 0.7.5\n - fix show all display issue\n - 0.7.4\n - optimize tag/route, move to left. \n - fresh on change, no need to click generate any more.\n - 0.7.3\n - fix `module_color` failure\n - 0.7.2\n - keep links inside filtered nodes.\n - 0.7.1\n - support brief mode, you can use `--module_prefix tests.service` to show links between routes and filtered schemas, to make the graph less complicated.\n- 0.6: \n - 0.6.2: \n - fix generic related issue\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Visualize FastAPI application's routing tree and dependencies",
"version": "0.8.3",
"project_urls": {
"Homepage": "https://github.com/allmonday/fastapi-voyager",
"Source": "https://github.com/allmonday/fastapi-voyager"
},
"split_keywords": [
"fastapi",
" openapi",
" routing",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "29552684cf5b3bf52a98aa88f17402e1eeb3e4cb221eb620b0e4161d7cf91645",
"md5": "f3f2b3a04435c3ad0a306f1224ed9114",
"sha256": "16a5b991373aa5fb3de5df9ded70bd87dbd8d9e312c32ac928fa34557d18f97d"
},
"downloads": -1,
"filename": "fastapi_voyager-0.8.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f3f2b3a04435c3ad0a306f1224ed9114",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 524297,
"upload_time": "2025-10-19T13:11:05",
"upload_time_iso_8601": "2025-10-19T13:11:05.804466Z",
"url": "https://files.pythonhosted.org/packages/29/55/2684cf5b3bf52a98aa88f17402e1eeb3e4cb221eb620b0e4161d7cf91645/fastapi_voyager-0.8.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "95740dcc21b6e23fd91cc32cce0aa2fed16ae5b6cfdab3d615113c300e4d8ae3",
"md5": "a994d954bbd7f0216c1e6d0df9c31427",
"sha256": "b1da4a978ebf05ec9b4426123be3c8695310e6030f1c954099744d2ba723f9e5"
},
"downloads": -1,
"filename": "fastapi_voyager-0.8.3.tar.gz",
"has_sig": false,
"md5_digest": "a994d954bbd7f0216c1e6d0df9c31427",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 575039,
"upload_time": "2025-10-19T13:11:08",
"upload_time_iso_8601": "2025-10-19T13:11:08.244051Z",
"url": "https://files.pythonhosted.org/packages/95/74/0dcc21b6e23fd91cc32cce0aa2fed16ae5b6cfdab3d615113c300e4d8ae3/fastapi_voyager-0.8.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 13:11:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allmonday",
"github_project": "fastapi-voyager",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fastapi-voyager"
}
