Generate a diagram from an OpenAPI specification.
An OpenAPI document is exhaustive and unreadable. The useful diagram is not every endpoint, it is the shape underneath them.
What it reads
Paths and operations, the schemas under components, security schemes, servers, and tags. Tags matter more than they look: they are the author's own grouping of endpoints into areas, so they usually carry the resource model better than the path structure does, particularly in specs that have grown over time.
How a spec becomes a diagram
Endpoints are grouped into resources rather than drawn individually, because a diagram with one box per endpoint is the spec again in a less searchable form. Schemas referenced across several operations become shared entities, which is what shows you the actual data model. Security schemes become an authentication boundary at the front, and servers become the deployment targets.
Why the layout can be trusted
The agent reads the files listed above and emits a semantic graph: components, the tier each belongs to, and the edges between them, with no coordinates anywhere. The ELK layout engine then computes positions and orthogonal edge routing. This is why the output cannot come back with boxes overlapping or arrows crossing through cards, which is the usual failure when a language model is asked to place things on a canvas itself.
Sequence diagrams for the flows that matter
The more useful output is often not a component diagram but a sequence: what a client calls, in what order, to accomplish one thing. That ordering is not in the spec, since it describes endpoints rather than journeys, so this is where you describe the flow and let the diagram be drawn from the endpoints that exist.
Your spec stays on your machine
It runs on your machine. With a local Ollama model nothing leaves the laptop at all, and with your own API key the file contents go to the provider you chose and never through us. For a source that is your actual codebase, that distinction is usually the deciding one.
OpenAPI to diagram
| In the spec | In the diagram |
|---|---|
| paths grouped by tag | Resource components |
| Individual operations | Notes, or steps in a sequence |
| components.schemas | Shared entities |
| $ref reuse across operations | Edges between resources |
| securitySchemes | An authentication boundary |
| servers | Deployment targets |
| Webhooks and callbacks | Inbound edges from external systems |
The prompt
Questions
Swagger 2 or OpenAPI 3?
Both, and either JSON or YAML.
Can it produce a sequence diagram?
Yes. Describe the flow and it draws the ordering, using the spec to keep the operation names and parameters accurate.
What about GraphQL?
A GraphQL schema works too, and it is arguably a better source: the type graph is explicit rather than inferred from shared references.
Can it diagram an API from code instead?
Yes, by reading route registrations directly. That is usually more accurate than a spec, since the code cannot drift from itself.
Related
- Generate an AWS Architecture DiagramIt reads your infrastructure as files rather than by connecting to your account, which means it needs no credentials and works against environments you cannot reach.
- Generate a Diagram from a MonorepoThe hard part of diagramming a monorepo is not reading it, it is deciding what to leave out.
- Generate a Diagram from a Python ProjectPython projects hide their structure in decorators and imports, both of which are readable and neither of which is visible from a directory listing.
- Generate a Diagram from a TypeScript ProjectTypeScript projects usually have a real structure and a directory layout that obscures it, mostly because everything is a file that exports something.
Last updated