API and software flows
From an OpenAPI or Swagger file to a flowchart
An OpenAPI (or Swagger) file lists what an API can do, but not in what order a process uses it. To get a useful flowchart, combine the file with a short description of the process: the description gives the order and the decisions, and the specification gives the exact endpoint for each automated step.
OpenAPI and Swagger in one paragraph
The OpenAPI Specification is a standard format, in JSON or YAML, for describing HTTP APIs: their paths, operations, parameters and responses. It started as the Swagger Specification; version 2.0 is still widely called "Swagger 2", and the standard continued as OpenAPI 3.x. Tools use these files to generate documentation, clients and tests.
Why the spec alone is not enough
A specification is a catalogue: it says that POST /customers, POST /kyc-checks and POST /accounts exist. It does not say that a customer must pass the KYC check before the account is created, or what happens when the check fails. That order and those rules are the business process, and they live in people's heads or in other documents.
The combined approach
- Describe the process in a few sentences, naming who or what does each step: see how to describe a process for AI.
- Attach the specification (OpenAPI 3 or Swagger 2, as
.json,.yamlor.yml). - Generate: the steps come from your description; automated steps performed by the system are matched to the most relevant endpoint and labelled with it, such as
POST /kyc-checks. - Review the bindings: check that each endpoint is the one actually called, and fix any mismatch by asking, for example "use PUT /accounts/{id} for the activation step".
What Flowchartio reads from the file
Flowchartio detects OpenAPI and Swagger files, lists their operations as "METHOD /path", and uses them during generation. Files are limited to 5 MB. Other JSON, YAML and XML files are accepted as context, and SOAP services can be imported from their WSDL.
A short example
Description: "A visitor signs up. The system creates the customer, then runs the KYC check. If the check fails, the customer is informed. Otherwise the system opens the account and sends a welcome email." With a spec containing those endpoints, the result has a System lane where "Create customer", "Run KYC check", "Open account" and "Send welcome email" each carry their endpoint, plus a decision on the KYC result.
Use the result
- Share it with product and support teams who do not read specifications.
- Paste the Mermaid export in the repository next to the spec; see Mermaid on GitHub and GitLab.
- Extend it into full integration documentation with retries and errors: documenting an API integration workflow.
Turn your process into a flowchart
Describe it in a few sentences. Flowchartio draws the flowchart, then you refine it in conversation.
Generate a flowchart