x-openapi-flow 1.4.1 β 1.4.3
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 +35 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/x-openapi-flow)
|
|
6
6
|
[](https://www.npmjs.com/package/x-openapi-flow)
|
|
7
|
+
|
|
7
8
|
|
|
8
9
|
|
|
9
10
|
[](https://github.com/tiago-marques/x-openapi-flow/actions/workflows/x-openapi-flow-validate.yml)
|
|
@@ -14,23 +15,42 @@
|
|
|
14
15
|
|
|
15
16
|
# OpenAPI describes APIs. x-openapi-flow describes their workflows β for developers and AI.
|
|
16
17
|
|
|
17
|
-
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
> See your API lifecycle come alive from your OpenAPI spec, with one simple command
|
|
22
|
+
|
|
23
|
+
> Validate, document, and generate flow-aware SDKs automatically.
|
|
19
24
|
|
|
20
25
|
`x-openapi-flow` adds a **declarative state machine** to your OpenAPI spec.
|
|
21
26
|
|
|
22
27
|
Model resource lifecycles, enforce valid transitions, and generate flow-aware artifacts for documentation, SDKs, and automation.
|
|
23
28
|
|
|
29
|
+
## Why This Exists
|
|
30
|
+
|
|
31
|
+
Building APIs is cheap. Building **complex, multi-step APIs that teams actually use correctly** is hard.
|
|
32
|
+
|
|
33
|
+
Teams face recurring problems:
|
|
34
|
+
|
|
35
|
+
- π **Manual documentation is brittle** β OpenAPI specs are static, often out of sync with real workflows
|
|
36
|
+
- π€ **AI agents can hallucinate** β LLMs and code-generating agents may produce invalid calls if workflows are unclear or undocumented
|
|
37
|
+
- π€― **Workflows are confusing** β multi-step operations are hard to track for humans and AI agents
|
|
38
|
+
- β οΈ **Invalid calls slip through** β developers make mistakes because lifecycle rules arenβt enforced
|
|
39
|
+
- β±οΈ **Integration slows down** β SDKs, Postman collections, and docs need constant manual updates
|
|
40
|
+
- π‘οΈ **Hard to prevent errors in production** β without explicit lifecycle rules, invalid operations can reach live systems, causing outages or inconsistencies
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
x-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**.
|
|
24
44
|
|
|
25
45
|
## What This Enables
|
|
26
46
|
|
|
27
47
|
Turn your OpenAPI spec into a single source of truth for API behavior:
|
|
28
|
-
- Visualize API lifecycles directly in Swagger UI and Redoc
|
|
29
|
-
- Validate flows and state transitions in CI pipelines
|
|
30
|
-
- Generate lifecycle diagrams automatically from your OpenAPI spec
|
|
31
|
-
- Build SDKs that understand and respect API workflows
|
|
32
|
-
- Export Postman
|
|
33
|
-
- Create AI-ready API contracts for agentic integrations
|
|
48
|
+
- Visualize API lifecycles directly in [Swagger UI](#swagger-ui-demo) and [Redoc](#redoc-demo)
|
|
49
|
+
- Validate flows and state transitions in [CI pipelines](#cli-commands)
|
|
50
|
+
- Generate [lifecycle diagrams automatically](#mermaid-example) from your OpenAPI spec
|
|
51
|
+
- Build [SDKs](#sdk-generation) that understand and respect API workflows
|
|
52
|
+
- Export [Postman](#postman-demo) and [Insomnia](#insomnia-demo) collections organized by lifecycle
|
|
53
|
+
- 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
|
|
34
54
|
|
|
35
55
|
## Quick Start
|
|
36
56
|
|
|
@@ -56,6 +76,7 @@ This will:
|
|
|
56
76
|
|
|
57
77
|
π‘ Tip: run this in CI to enforce API workflow correctness
|
|
58
78
|
|
|
79
|
+
<a id="mermaid-example"></a>
|
|
59
80
|
### Real Lifecycle Example
|
|
60
81
|
|
|
61
82
|
Hereβs a real-world payment lifecycle represented in x-openapi-flow:
|
|
@@ -81,6 +102,7 @@ CAPTURED --> REFUNDED
|
|
|
81
102
|
|
|
82
103
|
> This visualization makes your API workflow explicit, easy to communicate, and ready for documentation or demos.
|
|
83
104
|
|
|
105
|
+
<a id="sdk-generation"></a>
|
|
84
106
|
## Generate Flow-Aware SDKs
|
|
85
107
|
|
|
86
108
|
Create a TypeScript SDK that **respects your APIβs lifecycle and transition rules**, following best practices seen in leading companies like **Stripe** and **Adyen**:
|
|
@@ -129,6 +151,7 @@ See how **x-openapi-flow extends OpenAPI** to make your API workflows explicit,
|
|
|
129
151
|
|
|
130
152
|
Explore how x-openapi-flow integrates with popular API tools, making lifecycles and flows explicit for documentation and testing.
|
|
131
153
|
|
|
154
|
+
<a id="swagger-ui-demo"></a>
|
|
132
155
|
### Swagger UI β Visualize Flows in Your Docs
|
|
133
156
|
|
|
134
157
|
```bash
|
|
@@ -144,6 +167,7 @@ npm start
|
|
|
144
167
|
|
|
145
168
|
> Detailed view of transitions per operation
|
|
146
169
|
|
|
170
|
+
<a id="redoc-demo"></a>
|
|
147
171
|
### Redoc β Flow-Aware Documentation
|
|
148
172
|
|
|
149
173
|
```bash
|
|
@@ -158,6 +182,7 @@ npm run generate
|
|
|
158
182
|
|
|
159
183
|
> Auto-generated lifecycle diagrams make documentation clear and consistent
|
|
160
184
|
|
|
185
|
+
<a id="postman-demo"></a>
|
|
161
186
|
### Postman β Organized API Collections
|
|
162
187
|
|
|
163
188
|
```bash
|
|
@@ -171,6 +196,7 @@ npm run generate
|
|
|
171
196
|
|
|
172
197
|
> Collections reflect lifecycle order, reducing integration errors
|
|
173
198
|
|
|
199
|
+
<a id="insomnia-demo"></a>
|
|
174
200
|
### Insomnia β Organized API Collections
|
|
175
201
|
|
|
176
202
|
```bash
|
|
@@ -184,6 +210,7 @@ npm run generate
|
|
|
184
210
|
|
|
185
211
|
> Requests are pre-organized according to lifecycle transitions
|
|
186
212
|
|
|
213
|
+
<a id="cli-commands"></a>
|
|
187
214
|
## CLI Reference β Common Commands
|
|
188
215
|
|
|
189
216
|
Use x-openapi-flow from the command line to **manage, validate, visualize, and generate SDKs/docs for your API workflows**.
|