Convert an OpenAPI spec into a sequence diagram.
The spec supplies the operations and their exact names. You supply the ordering, because a spec describes endpoints and not journeys.
What the spec gives you
Accurate participants, operation names, parameters and response codes. That accuracy is the point: a sequence diagram with invented endpoint names is worse than none, because it looks authoritative and misleads anyone implementing against it.
What you have to supply
The ordering. An OpenAPI document describes what endpoints exist, not which a client calls in what sequence to accomplish something, and no amount of reading will recover that. Describing the flow in a sentence is the input; the spec keeps the details honest.
Failure branches are the valuable part
Response codes in the spec tell you what can go wrong, and drawing the alternative path, what the client does on a 409 or a 429, is usually the content someone actually needed. Happy-path-only sequence diagrams are common and are the least useful version of this artifact.
Fidelity
| Comes through | Does not | |
|---|---|---|
| Operations | Real paths and methods | |
| Participants | From tags and servers | |
| Parameters | On the message | Full schemas, which would swamp it |
| Response codes | As alternative branches | |
| Authentication | As a boundary or preliminary step | |
| Ordering | Not in the spec, you describe it | |
| Retries and timeouts | Client behaviour, you describe it | |
| Webhooks | As inbound messages |
The prompt
Questions
Swagger 2 or OpenAPI 3?
Both, in JSON or YAML.
Can it work out the flow itself?
It will propose a plausible one, and plausible is the risk: the spec does not contain the answer, so check it rather than trusting it.
What about GraphQL?
It works, and the type graph is arguably a better source since relationships are explicit rather than implied by shared references.
Related
- Convert Docker Compose to a DiagramA Compose file is a complete description of a small system written in a format that hides its shape.
- Convert Kubernetes YAML to a DiagramThe whole topology is in the YAML, expressed as label matches spread across forty files.
- Convert Excalidraw to SVGA small utility, published because it solved a real problem here and the usual approach needs a DOM and about 1.4 MB of dependencies.
- Convert Mermaid to an Architecture DiagramMermaid gives you the graph. What it cannot give you is tiers, icons, and a layout that survives the diagram growing.
Last updated