A tool for visualizing OpenAPI schemas as graphs.
Based on Swagger Petstore example
See Interactive HTML Viewer example
Based on a NASA OpenAPI spec
- Visualizes OpenAPI schemas as graphs
- Supports different types of schema components:
- Simple types (string, integer, boolean, etc.)
- Array types
- Object types with properties
- Reference types
- AnyOf types (multiple possible types)
- Generates SVG output for easy embedding in documentation
- Provides an interactive HTML viewer for exploring the generated graphs
-
Clone the repository:
git clone https://github.com/karlll/openapi-viz.git cd openapi-viz -
Install dependencies:
uv install -e . -
For development, install development dependencies:
uv install -e ".[dev]"
Basic usage:
python openapi-viz.py /path/to/your/openapi.yamlThis will generate a graph visualization of the OpenAPI schema and save it as api_graph.svg.
Specify a custom output filename:
python openapi-viz.py /path/to/your/openapi.yaml -o custom_outputThis will save the graph as custom_output.svg.
Generate an HTML viewer for the graph:
python openapi-viz.py /path/to/your/openapi.yaml -vThis will generate an HTML file (api_graph.html) that embeds the SVG in an interactive viewer.
You can also combine options:
python openapi-viz.py /path/to/your/openapi.yaml -o custom_output -vThis will save the graph as an HTML viewer at custom_output.html.
Generate a DOT file for the graph:
python openapi-viz.py /path/to/your/openapi.yaml --dotThis will generate a DOT file (api_graph.dot) representing the graph structure.
usage: openapi-viz.py [-h] [-o OUTPUT] [-v] [--dot] input_file
Generate a graph visualization of an OpenAPI schema.
positional arguments:
input_file Path to the OpenAPI schema file (YAML or JSON)
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
Output file name (without extension, default: api_graph)
-v, --viewer Embed the SVG in an HTML viewer
--dot Export the graph in DOT format
You can also use the OpenAPIGraphGenerator class directly in your Python code:
# If you have the script in your project
from openapi_viz import OpenAPIGraphGenerator
# Or import it from a file path
import importlib.util
spec = importlib.util.spec_from_file_location("openapi_viz", "/path/to/openapi-viz.py")
openapi_viz = importlib.util.module_from_spec(spec)
spec.loader.exec_module(openapi_viz)
OpenAPIGraphGenerator = openapi_viz.OpenAPIGraphGenerator
# Then use it
generator = OpenAPIGraphGenerator('/path/to/your/openapi.yaml')
graph = generator.generate_graph()
# Save as SVG
output_file = generator.save('output_filename')
print(f"Graph saved to {output_file}")
# Or save as HTML viewer
output_file = generator.save('output_filename', use_viewer=True)
print(f"Graph saved to {output_file} (HTML viewer)")Run the tests with pytest:
pytestFor test coverage report:
pytest --cov=.