x-openapi-flow 1.5.0 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
<!-- Auto-generated from /README.md via scripts/sync-package-readme.js. Do not edit directly. -->
|
|
2
2
|
|
|
3
|
+
# OpenAPI describes APIs. x-openapi-flow turns them into executable workflows — for developers and AI agents.
|
|
4
|
+
|
|
5
|
+
## Define your API workflows in openapi.x.json and execute them without writing custom clients or orchestration logic.
|
|
6
|
+
|
|
3
7
|
|
|
4
8
|
|
|
5
9
|
[](https://www.npmjs.com/package/x-openapi-flow)
|
|
@@ -11,21 +15,69 @@
|
|
|
11
15
|
[](https://github.com/tiago-marques/x-openapi-flow/issues)
|
|
12
16
|
[](https://github.com/tiago-marques/x-openapi-flow/commits/main)
|
|
13
17
|
|
|
14
|
-
> 🚀
|
|
15
|
-
|
|
16
|
-
# OpenAPI describes APIs. x-openapi-flow describes their workflows — for developers and AI.
|
|
18
|
+
> 🚀 2,100+ downloads in the first 3 weeks!
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
## ⚡ Get started in seconds
|
|
21
|
+
> npx x-openapi-flow init
|
|
19
22
|
|
|
23
|
+
### This generates an openapi.x.json file where you can declaratively define how your API should be executed — not just described.
|
|
20
24
|
|
|
21
25
|
> See your API lifecycle come alive from your OpenAPI spec, with one simple command
|
|
22
26
|
|
|
23
27
|
> Validate, document, and generate flow-aware SDKs automatically.
|
|
24
28
|
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
## What is this?
|
|
32
|
+
|
|
33
|
+
### x-openapi-flow extends your OpenAPI specification with a workflow layer.
|
|
34
|
+
|
|
35
|
+
> openapi.json → describes your API
|
|
36
|
+
> openapi.x.json → describes how to use it (flows)
|
|
37
|
+
|
|
38
|
+
### Instead of writing imperative code to orchestrate API calls, you define workflows declaratively and run them anywhere.
|
|
39
|
+
|
|
25
40
|
`x-openapi-flow` adds a **declarative state machine** to your OpenAPI spec.
|
|
26
41
|
|
|
27
42
|
Model resource lifecycles, enforce valid transitions, and generate flow-aware artifacts for documentation, SDKs, and automation.
|
|
28
43
|
|
|
44
|
+
## 🚀 Example
|
|
45
|
+
|
|
46
|
+
> Define stateful workflows and lifecycle transitions directly inside your OpenAPI operations:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"operationId": "createOrder",
|
|
51
|
+
"x-openapi-flow": {
|
|
52
|
+
"id": "create-order",
|
|
53
|
+
"current_state": "created",
|
|
54
|
+
"description": "Creates an order and starts the lifecycle",
|
|
55
|
+
"transitions": [
|
|
56
|
+
{
|
|
57
|
+
"trigger_type": "synchronous",
|
|
58
|
+
"condition": "Payment is confirmed",
|
|
59
|
+
"target_state": "paid",
|
|
60
|
+
"next_operation_id": "payOrder",
|
|
61
|
+
"prerequisite_operation_ids": ["createOrder"],
|
|
62
|
+
"propagated_field_refs": [
|
|
63
|
+
"createOrder:response.201.body.order_id"
|
|
64
|
+
]
|
|
65
|
+
}
|
|
66
|
+
]
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
This flow defines an order lifecycle directly inside your OpenAPI:
|
|
72
|
+
|
|
73
|
+
* Starts in the `created` state
|
|
74
|
+
* Transitions to `paid` when payment is confirmed
|
|
75
|
+
* Supports both synchronous and polling-based transitions
|
|
76
|
+
* Propagates data between operations automatically
|
|
77
|
+
|
|
78
|
+
Instead of manually orchestrating API calls, the workflow is fully described alongside your API specification.
|
|
79
|
+
|
|
80
|
+
|
|
29
81
|
## Why This Exists
|
|
30
82
|
|
|
31
83
|
Building APIs is cheap. Building **complex, multi-step APIs that teams actually use correctly** is hard.
|
|
@@ -52,7 +104,7 @@ Turn your OpenAPI spec into a single source of truth for API behavior:
|
|
|
52
104
|
- Export [Postman](#postman-demo) and [Insomnia](#insomnia-demo) collections organized by lifecycle
|
|
53
105
|
- 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
|
|
54
106
|
|
|
55
|
-
## Quick Start
|
|
107
|
+
## Quick Start (without OpenAPI file)
|
|
56
108
|
|
|
57
109
|
Fastest way to see value (guided scaffold):
|
|
58
110
|
|
|
@@ -79,8 +131,10 @@ curl -i -X POST http://localhost:3110/orders/<id>/ship
|
|
|
79
131
|
Expected: `409 INVALID_STATE_TRANSITION`.
|
|
80
132
|
|
|
81
133
|
---
|
|
134
|
+
### If you already have an OpenAPI file, use the sidecar workflow:
|
|
135
|
+
|
|
136
|
+
|
|
82
137
|
|
|
83
|
-
If you already have an OpenAPI file, use the sidecar workflow:
|
|
84
138
|
|
|
85
139
|
Initialize flow support in your project:
|
|
86
140
|
|