When working on complex APIs, I noticed that OpenAPI defines endpoints but does not capture how these endpoints should actually be used over time. Lifecycle rules, allowed state transitions, and prerequisites for actions are often implicit, which leads to integration errors and CI pipelines rarely catching them early.
To address this, I started building x-openapi-flow, a vendor extension and CLI that adds explicit lifecycle and state-machine metadata to OpenAPI operations. The tool lets you represent API flows as graphs of states and transitions, validates them automatically, and generates flow-aware SDKs, Postman and Insomnia collections, and documentation.
There were several technical challenges. First, sidecar metadata needed to survive OpenAPI regeneration while remaining mergeable. Second, modeling the state-machine required tracking prerequisites, next states, and propagated fields while ensuring the graph stayed acyclic and complete. Third, integrating with Swagger UI, Redoc, and SDK generation required careful abstractions to provide a smooth developer experience. Finally, the SDKs had to guide developers through valid transitions rather than leaving them to figure it out manually.
A big part of building this was using GitHub Copilot. Copilot accelerated boilerplate tasks such as generating TypeScript SDK scaffolding, merging JSON and YAML sidecars, and writing validation logic. It allowed me to iterate quickly on graph traversal, validation rules, and lifecycle inference. Even though Copilot suggested implementations, the design decisions about correctness and usability were mine. This experience showed that AI-assisted coding works best when paired with a clear architectural vision.
The repository contains full examples of common lifecycles, including payments and orders, as well as CLI tooling to experiment with flow-aware validation, graph generation, and SDKs. It has been very useful to see how AI can assist in building complex developer tooling while keeping control over the design and correctness.
Top comments (0)