{"id":45726477,"url":"https://github.com/tiago-marques/x-openapi-flow","last_synced_at":"2026-04-02T20:57:04.055Z","repository":{"id":340422038,"uuid":"1165985695","full_name":"tiago-marques/x-openapi-flow","owner":"tiago-marques","description":"OpenAPI describes APIs. _________    x-openapi-flow describes how they actually work: for developers and AI.","archived":false,"fork":false,"pushed_at":"2026-03-18T21:52:53.000Z","size":4733,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T02:34:24.231Z","etag":null,"topics":["cli","lifecycle","oas","openapi","validation","workflow"],"latest_commit_sha":null,"homepage":"https://tiago-marques.github.io/x-openapi-flow/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiago-marques.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T18:56:51.000Z","updated_at":"2026-03-18T21:52:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tiago-marques/x-openapi-flow","commit_stats":null,"previous_names":["tiago-marques/x-flow","tiago-marques/x-openapi-flow"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/tiago-marques/x-openapi-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiago-marques%2Fx-openapi-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiago-marques%2Fx-openapi-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiago-marques%2Fx-openapi-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiago-marques%2Fx-openapi-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiago-marques","download_url":"https://codeload.github.com/tiago-marques/x-openapi-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiago-marques%2Fx-openapi-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31314864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","lifecycle","oas","openapi","validation","workflow"],"created_at":"2026-02-25T08:29:47.229Z","updated_at":"2026-04-02T20:57:04.046Z","avatar_url":"https://github.com/tiago-marques.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI describes APIs. x-openapi-flow turns them into executable workflows — for developers and AI agents.\n\n## Define your API workflows in openapi.x.json and execute them without writing custom clients or orchestration logic\n\n![x-openapi-flow logo](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/x-openapi-flow-logo.svg)\n\n[![npm version](https://img.shields.io/npm/v/x-openapi-flow?label=npm%20version)](https://www.npmjs.com/package/x-openapi-flow)\n[![npm downloads](https://img.shields.io/npm/dm/x-openapi-flow?label=npm%20downloads)](https://www.npmjs.com/package/x-openapi-flow)\n![npm total downloads](https://img.shields.io/npm/dt/x-openapi-flow?style=flat-square)\n![node](https://img.shields.io/badge/node-%3E%3D18-339933)\n![license](https://img.shields.io/npm/l/x-openapi-flow)\n[![CI](https://github.com/tiago-marques/x-openapi-flow/actions/workflows/x-openapi-flow-validate.yml/badge.svg)](https://github.com/tiago-marques/x-openapi-flow/actions/workflows/x-openapi-flow-validate.yml)\n[![open issues](https://img.shields.io/github/issues/tiago-marques/x-openapi-flow)](https://github.com/tiago-marques/x-openapi-flow/issues)\n[![last commit](https://img.shields.io/github/last-commit/tiago-marques/x-openapi-flow)](https://github.com/tiago-marques/x-openapi-flow/commits/main)\n![copilot ready](https://img.shields.io/badge/Copilot-Ready-00BFA5?logo=githubcopilot\u0026logoColor=white)\n\u003e 🚀 2,100+ downloads in the first 3 weeks!\n\n## ⚡ Get started in seconds\n```\nnpx x-openapi-flow init --suggest-transitions\n```\n\n### This generates an openapi.x.json file where you can declaratively define how your API should be executed — not just described.\n\n\u003e See your API lifecycle come alive from your OpenAPI spec, with one simple command\n\n\u003e Validate, document, and generate flow-aware SDKs automatically.\n\n![x-openapi-flow in action](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/ezgif.com-animated-gif-maker.gif)\n\n## What is this?\n\n### x-openapi-flow extends your OpenAPI specification with a workflow layer.\n\n\u003e openapi.json → describes your API  \n\u003e openapi.x.json → describes how to use it (flows)\n\n### Instead of writing imperative code to orchestrate API calls, you define workflows declaratively and run them anywhere.\n\n`x-openapi-flow` adds a **declarative state machine** to your OpenAPI spec.\n\nModel resource lifecycles, enforce valid transitions, and generate flow-aware artifacts for documentation, SDKs, and automation.\n\n## 🚀 Example\n\n\u003e Define stateful workflows and lifecycle transitions directly inside your OpenAPI operations:\n\n```json\n{\n  \"operationId\": \"createOrder\",\n  \"x-openapi-flow\": {\n    \"version\": \"1.0\",\n    \"id\": \"create-order\",\n    \"current_state\": \"created\",\n    \"description\": \"Creates an order and starts the lifecycle\",\n    \"transitions\": [\n      {\n        \"transition_id\": \"order-created-to-paid\",\n        \"trigger_type\": \"synchronous\",\n        \"condition\": \"Payment is confirmed\",\n        \"decision_rule\": \"payOrder:response.200.body.payment_status == 'approved'\",\n        \"target_state\": \"paid\",\n        \"next_operation_id\": \"payOrder\",\n        \"operation_role\": \"mutate\",\n        \"prerequisite_operation_ids\": [\"createOrder\"],\n        \"evidence_refs\": [\n          \"payOrder:response.200.body.payment_status\"\n        ],\n        \"propagated_field_refs\": [\n          \"createOrder:response.201.body.order_id\"\n        ],\n        \"failure_paths\": [\n          {\n            \"reason\": \"Payment denied\",\n            \"target_state\": \"payment_failed\",\n            \"next_operation_id\": \"getOrder\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThis flow defines an order lifecycle directly inside your OpenAPI:\n\n* Starts in the `created` state\n* Transitions to `paid` when payment is confirmed\n* Supports both synchronous and polling-based transitions\n* Propagates data between operations automatically\n* Can include explicit decision/evidence and failure-path metadata for AI-guided orchestration\n\nInstead of manually orchestrating API calls, the workflow is fully described alongside your API specification.\n\n## Why This Exists\n\nBuilding APIs is cheap. Building **complex, multi-step APIs that teams actually use correctly** is hard.  \n\nTeams face recurring problems:\n\n- 📄 **Manual documentation is brittle** – OpenAPI specs are static, often out of sync with real workflows  \n- 🤖 **AI agents can hallucinate** – LLMs and code-generating agents may produce invalid calls if workflows are unclear or undocumented  \n- 🤯 **Workflows are confusing** – multi-step operations are hard to track for humans and AI agents \n- ⚠️ **Invalid calls slip through** – developers make mistakes because lifecycle rules aren’t enforced  \n- ⏱️ **Integration slows down** – SDKs, Postman collections, and docs need constant manual updates  \n- 🛡️ **Hard to prevent errors in production** – without explicit lifecycle rules, invalid operations can reach live systems, causing outages or inconsistencies  \n\n\nx-openapi-flow exists to **solve these pains**: it makes lifecycles explicit, validates transitions automatically, and generates flow-aware docs and SDKs — **so teams move faster, make fewer mistakes, and ship confident integrations**.\n\n## What This Enables\n\nTurn your OpenAPI spec into a single source of truth for API behavior:\n- Visualize API lifecycles directly in [Swagger UI](#swagger-ui-demo) and [Redoc](#redoc-demo)\n- Validate flows and state transitions in [CI pipelines](#cli-commands)\n- Generate [lifecycle diagrams automatically](#mermaid-example) from your OpenAPI spec\n- Build [SDKs](#sdk-generation) that understand and respect API workflows\n- Export [Postman](#postman-demo) and [Insomnia](#insomnia-demo) collections organized by lifecycle\n- Create [AI-ready API contracts](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/AI-Sidecar-Authoring.md) for agentic integrations\n\n## Quick Start (without OpenAPI file)\n\nFastest way to see value (guided scaffold):\n\n```bash\nnpx x-openapi-flow quickstart\ncd x-openapi-flow-quickstart\nnpm install\nnpm start\n```\n\nOptional runtime:\n\n```bash\nnpx x-openapi-flow quickstart --runtime fastify\n```\n\nThen run:\n\n```bash\ncurl -s -X POST http://localhost:3110/orders\ncurl -i -X POST http://localhost:3110/orders/\u003cid\u003e/ship\n```\n\nExpected: `409 INVALID_STATE_TRANSITION`.\n\n---\n### If you already have an OpenAPI file, use the sidecar workflow:\n\n\n\n\nInitialize flow support in your project:\n\n```bash\nnpx x-openapi-flow init\n# optional: infer suggested transitions using naming heuristics\nnpx x-openapi-flow init --suggest-transitions\n```\n\nAfter regenerating your OpenAPI file, apply and validate the flow (optional):\n\n```bash\nnpx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml\n\nnpx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality\n```\n\nThis will:\n\n- enrich your OpenAPI spec with flow metadata\n- validate lifecycle consistency\n- catch invalid transitions early\n\n💡 Tip: run this in CI to enforce API workflow correctness\n\n### Less Verbose DSL for Large Flows\n\nFor larger APIs, you can define flow rules by resource (with shared transitions/defaults) and reduce duplication in sidecar files.\n\nSee: [Sidecar Contract](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Sidecar-Contract.md)\n\n### GitHub Action (One-Step CI Validation)\n\nUse the official reusable action to validate lifecycle rules in CI with a single step:\n\n```yaml\n- name: Validate OpenAPI flow rules\n  uses: tiago-marques/x-openapi-flow/.github/actions/validate@main\n  with:\n    openapi-file: openapi.flow.yaml\n    profile: strict\n    strict-quality: \"true\"\n```\n\nIntegration guide: [GitHub-Actions-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/GitHub-Actions-Integration.md)\n\n\u003ca id=\"mermaid-example\"\u003e\u003c/a\u003e\n### Real Lifecycle Example\n\nHere’s a real-world payment lifecycle represented in x-openapi-flow:\n\n```\nCREATED -\u003e AUTHORIZED -\u003e CAPTURED -\u003e REFUNDED\n```\n\nGenerate a visual graph of the lifecycle:\n\n```bash\nnpx x-openapi-flow graph openapi.flow.yaml --format mermaid\n```\n\nResulting diagram:\n\n```mermaid\ngraph TD\nCREATED --\u003e AUTHORIZED\nAUTHORIZED --\u003e CAPTURED\nCAPTURED --\u003e REFUNDED\n```\n\n\u003e This visualization makes your API workflow explicit, easy to communicate, and ready for documentation or demos.\n\n\u003ca id=\"sdk-generation\"\u003e\u003c/a\u003e\n## Generate Flow-Aware SDKs\n\nCreate a TypeScript SDK that **respects your API’s lifecycle and transition rules**, following best practices seen in leading companies like **Stripe** and **Adyen**:\n\n- **Orchestrator by model**: each resource exposes methods that enforce valid transitions\n- **Chainable API calls**: perform sequences naturally and safely\n\n```bash\nnpx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk\n```\n\nExample usage:\n\n```ts\nconst payment = await sdk.payments.create({ amount: 1000 });\nawait payment.authorize();\nawait payment.capture();\n```\n\n\u003e This SDK guides developers through valid transition paths, following patterns used by market leaders to ensure safe and intuitive integrations.\n\n## Runtime Enforcement (Express + Fastify)\n\nCI validation is important, but production safety needs request-time enforcement.\n\n`x-openapi-flow` now includes an official runtime guard for Node.js that can block invalid state transitions during request handling.\n\n- Works with **Express** and **Fastify**\n- Resolves operations by `operationId` (when available) or by method + route\n- Reads current resource state using your own persistence callback\n- Blocks invalid transitions with explicit `409` error payloads\n\nInstall and use directly in your API server:\n\n```js\nconst {\n  createExpressFlowGuard,\n  createFastifyFlowGuard,\n} = require(\"x-openapi-flow/lib/runtime-guard\");\n```\n\nExpress example:\n\n```js\nconst express = require(\"express\");\nconst { createExpressFlowGuard } = require(\"x-openapi-flow/lib/runtime-guard\");\nconst openapi = require(\"./openapi.flow.json\");\n\nconst app = express();\n\napp.use(\n  createExpressFlowGuard({\n    openapi,\n    async getCurrentState({ resourceId }) {\n      if (!resourceId) return null;\n      return paymentStore.getState(resourceId); // your DB/service lookup\n    },\n    resolveResourceId: ({ params }) =\u003e params.id || null,\n  })\n);\n```\n\nFastify example:\n\n```js\nconst fastify = require(\"fastify\")();\nconst { createFastifyFlowGuard } = require(\"x-openapi-flow/lib/runtime-guard\");\nconst openapi = require(\"./openapi.flow.json\");\n\nfastify.addHook(\n  \"preHandler\",\n  createFastifyFlowGuard({\n    openapi,\n    async getCurrentState({ resourceId }) {\n      if (!resourceId) return null;\n      return paymentStore.getState(resourceId);\n    },\n    resolveResourceId: ({ params }) =\u003e params.id || null,\n  })\n);\n```\n\nError payload for blocked transition:\n\n```json\n{\n  \"error\": {\n    \"code\": \"INVALID_STATE_TRANSITION\",\n    \"message\": \"Blocked invalid transition for operation 'capturePayment'. Current state 'CREATED' cannot transition to this operation.\",\n    \"operation_id\": \"capturePayment\",\n    \"current_state\": \"CREATED\",\n    \"allowed_from_states\": [\"AUTHORIZED\"],\n    \"resource_id\": \"pay_123\"\n  }\n}\n```\n\nMore details: [Runtime Guard](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Runtime-Guard.md)\n\n### 5-Minute Demo: Real Runtime Block (E-commerce Orders)\n\nWant to see the value immediately? Use the official minimal demo:\n\n- [example/runtime-guard/minimal-order/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/example/runtime-guard/minimal-order/README.md)\n\nRun in under 5 minutes:\n\n```bash\ncd example/runtime-guard/minimal-order\nnpm install\nnpm start\n```\n\nCreate an order, then try to ship before payment (must return `409 INVALID_STATE_TRANSITION`):\n\n```bash\ncurl -s -X POST http://localhost:3110/orders\ncurl -i -X POST http://localhost:3110/orders/\u003cid\u003e/ship\n```\n\nHTTPie equivalent:\n\n```bash\nhttp POST :3110/orders\nhttp -v POST :3110/orders/\u003cid\u003e/ship\n```\n\n## Programmatic State Machine Engine\n\nUse a reusable deterministic engine independently of CLI and OpenAPI parsing:\n\n```js\nconst { createStateMachineEngine } = require(\"x-openapi-flow/lib/state-machine-engine\");\n\nconst engine = createStateMachineEngine({\n  transitions: [\n    { from: \"CREATED\", action: \"confirm\", to: \"CONFIRMED\" },\n    { from: \"CONFIRMED\", action: \"ship\", to: \"SHIPPED\" },\n  ],\n});\n\nengine.canTransition(\"CREATED\", \"confirm\");\nengine.getNextState(\"CREATED\", \"confirm\");\nengine.validateFlow({ startState: \"CREATED\", actions: [\"confirm\", \"ship\"] });\n```\n\nMore details: [State Machine Engine](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/State-Machine-Engine.md)\n\n### OpenAPI to Engine Adapter\n\nConvert `x-openapi-flow` metadata to a pure engine definition:\n\n```js\nconst { createStateMachineAdapterModel } = require(\"x-openapi-flow/lib/openapi-state-machine-adapter\");\nconst { createStateMachineEngine } = require(\"x-openapi-flow/lib/state-machine-engine\");\n\nconst model = createStateMachineAdapterModel({ openapiPath: \"./openapi.flow.yaml\" });\nconst engine = createStateMachineEngine(model.definition);\n```\n\nMore details: [OpenAPI State Machine Adapter](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/OpenAPI-State-Machine-Adapter.md)\n\n## Who Benefits Most\n\nx-openapi-flow is ideal for teams and organizations that want **clear, enforceable API workflows**:\n\n- **API-first organizations** – maintain a single source of truth for API behavior  \n- **Teams building AI agents** – provide AI-friendly contracts and enforce correct API usage, so agents can safely call endpoints in the right order without guessing or violating workflow rules\n- **API platform teams** – ensure consistent lifecycle rules across endpoints  \n- **Companies with complex API workflows** – reduce errors and ambiguity in multi-step processes  \n- **SDK teams** – generate flow-aware SDKs that guide developers  \n\n\n## Why x-openapi-flow?\n\nSee how **x-openapi-flow extends OpenAPI** to make your API workflows explicit, enforceable, and actionable:\n\n| Capability | OpenAPI | x-openapi-flow |\n| --- | --- | --- |\n| Endpoint contracts | ✅ Yes | ✅ Yes (fully compatible, extended) |\n| Lifecycle states | ❌ No | ✅ Yes – define states for each resource |\n| Transition validation | ❌ No | ✅ Yes – catch invalid calls before runtime |\n| Flow diagrams | ❌ No | ✅ Yes – generate visual lifecycle graphs |\n| Usage guidance (next valid actions) | Limited/manual | ✅ Built-in via lifecycle metadata – guides developers and AI agents |\n\n## Integration Demos\n\nExplore how x-openapi-flow integrates with popular API tools, making lifecycles and flows explicit for documentation and testing.\n\n\u003ca id=\"swagger-ui-demo\"\u003e\u003c/a\u003e\n### Swagger UI – Visualize Flows in Your Docs\n\n```bash\ncd example/swagger-ui\nnpm install\nnpm run apply\nnpm start\n```\n\n![Swagger UI Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/swagger-ui-flow-lifecycle.png)\n\u003e Lifecycle panel shows valid states and transitions\n\n![Swagger UI Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/swagger-ui-flow-lifecycle-2.png)\n\u003e Detailed view of transitions per operation\n\n\u003ca id=\"redoc-demo\"\u003e\u003c/a\u003e\n### Redoc – Flow-Aware Documentation\n\n```bash\ncd example/redoc\nnpm install\nnpm run apply\nnpm run generate\n```\n\n![Redoc Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle.png)\n![Redoc Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle-2.png)\n![Redoc Flow Lifecycle 3](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle-3.png)\n\u003e Auto-generated lifecycle diagrams make documentation clear and consistent\n\n\u003ca id=\"postman-demo\"\u003e\u003c/a\u003e\n### Postman – Organized API Collections\n\n```bash\ncd example/postman\nnpm install\nnpm run apply\nnpm run generate\n```\n\n![Postman Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/postman-flow-lifecycle.png)\n![Postman Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/postman-flow-lifecycle-2.png)\n\u003e Collections reflect lifecycle order, reducing integration errors\n\n\u003ca id=\"insomnia-demo\"\u003e\u003c/a\u003e\n### Insomnia – Organized API Collections\n\n```bash\ncd example/insomnia\nnpm install\nnpm run apply\nnpm run generate\n```\n\n![Insomnia Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/insomnia-flow-lifecycle.png)\n![Insomnia Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/insomnia-flow-lifecycle-2.png)\n\u003e Requests are pre-organized according to lifecycle transitions\n\n\u003ca id=\"cli-commands\"\u003e\u003c/a\u003e\n## CLI Reference – Common Commands\n\nUse x-openapi-flow from the command line to **manage, validate, visualize, and generate SDKs/docs for your API workflows**.  \n\n### General\n\n```bash\nnpx x-openapi-flow help [command]         # show help for a specific command\n\nnpx x-openapi-flow --help                 # general help\n\nnpx x-openapi-flow version                # show version\n\nnpx x-openapi-flow doctor [--config path] # check setup and config\n\nnpx x-openapi-flow completion [bash|zsh]  # enable shell autocompletion\n\nnpx x-openapi-flow quickstart [--dir path] [--runtime express|fastify] [--force] # scaffold runnable onboarding project\n```\n\n### Workflow Management\n\n```bash\n# initialize flow support\nnpx x-openapi-flow init [--flows path] [--force] [--dry-run]   \n\n# apply flows to OpenAPI\nnpx x-openapi-flow apply [openapi-file] [--flows path] [--out path]  \n\n# validate transitions\nnpx x-openapi-flow validate \u003copenapi-file\u003e [--profile core|relaxed|strict] [--strict-quality] [--semantic]  \n```\n\n### Visualization \u0026 Documentation\n\n```bash\n# generate lifecycle diagrams\nnpx x-openapi-flow graph [openapi-file] [--format mermaid|json]   \n\n# generate Redoc docs\nnpx x-openapi-flow generate-redoc [openapi-file] [--output path]   \n\n# export flows\nnpx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]  \n```\n\n### SDK Generation\n\n```bash\n# generate flow-aware SDK\nnpx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path] \n```\n\n### Test Generation\n\n```bash\n# generate executable flow tests (happy path + invalid transitions)\nnpx x-openapi-flow generate-flow-tests [openapi-file] [--format jest|vitest|postman] [--output path]\n\n# postman/newman-oriented collection with flow scripts\nnpx x-openapi-flow generate-flow-tests [openapi-file] --format postman [--output path] [--with-scripts]\n```\n\nFull details:  \n\n- [CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/CLI-Reference.md)  \n- [README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/README.md)\n\n## Documentation and Guides\n\nGet the most out of x-openapi-flow with detailed guides, examples, and integration instructions:\n\n- **Adoption Guide** – [docs/wiki/getting-started/Adoption-Playbook.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/getting-started/Adoption-Playbook.md)  \n  Learn how to introduce x-openapi-flow into your API workflow efficiently\n\n- **Troubleshooting** – [docs/wiki/reference/Troubleshooting.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Troubleshooting.md)  \n  Quick solutions to common issues and validation errors\n\n- **Real Examples** – [docs/wiki/engineering/Real-Examples.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/Real-Examples.md)  \n  Explore real OpenAPI specs enhanced with lifecycle metadata\n\n- **Integrations**:  \n  - **GitHub Actions** – [docs/wiki/integrations/GitHub-Actions-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/GitHub-Actions-Integration.md)  \n    Validate flow rules in CI in one reusable workflow step\n  - **Swagger UI** – [docs/wiki/integrations/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Swagger-UI-Integration.md)  \n    See flow-aware panels in Swagger UI  \n  - **Redoc** – [docs/wiki/integrations/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Redoc-Integration.md)  \n    Generate lifecycle diagrams in Redoc documentation  \n  - **Postman** – [docs/wiki/integrations/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Postman-Integration.md)  \n    Organize collections according to valid transitions  \n  - **Insomnia** – [docs/wiki/integrations/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Insomnia-Integration.md)  \n    Pre-configure requests according to lifecycle flows\n\n## Roadmap\n\nWe’re actively expanding x-openapi-flow to support multiple platforms and SDKs. Check our progress:\n\n- 🗂 **Roadmap Overview** – [#2](https://github.com/tiago-marques/x-openapi-flow/issues/2)  \n  See planned features and high-level goals\n\n- 🐍 **Python SDK MVP** – [#3](https://github.com/tiago-marques/x-openapi-flow/issues/3)  \n  Enable Python developers to use flow-aware SDKs\n\n- 🏎 **Go SDK MVP** – [#4](https://github.com/tiago-marques/x-openapi-flow/issues/4)  \n  Bring lifecycle-aware SDKs to Go projects\n\n- ☕ **Kotlin SDK MVP** – [#5](https://github.com/tiago-marques/x-openapi-flow/issues/5)  \n  Support Android and JVM developers with flow-aware SDKs\n\n## Changelog\n\nKeep track of updates and improvements in x-openapi-flow:\n\n- **Latest Version (v1.7.0)** – [CHANGELOG.md#170---2026-04-02](https://github.com/tiago-marques/x-openapi-flow/blob/main/CHANGELOG.md#170---2026-04-02)  \n  See what shipped in the current release\n\n- **Version History** – [CHANGELOG.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/CHANGELOG.md)  \n  Review the full version history and past updates\n\n- **Release Notes** – [GitHub Release v1.7.0](https://github.com/tiago-marques/x-openapi-flow/releases/tag/v1.7.0)  \n  See detailed notes for the latest release, including new features and fixes\n\n## Documentation Language Policy\n\nTo ensure clarity and accessibility for the global developer community, **all project documentation should be written in English**. This helps contributors, users, and AI agents understand and use x-openapi-flow consistently.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiago-marques%2Fx-openapi-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiago-marques%2Fx-openapi-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiago-marques%2Fx-openapi-flow/lists"}