x-openapi-flow 1.4.0 β 1.4.2
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 +172 -328
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,98 +10,144 @@
|
|
|
10
10
|
[](https://github.com/tiago-marques/x-openapi-flow/issues)
|
|
11
11
|
[](https://github.com/tiago-marques/x-openapi-flow/commits/main)
|
|
12
12
|
|
|
13
|
+
> π 1,400+ downloads in the first 3 weeks!
|
|
13
14
|
|
|
14
|
-
# OpenAPI describes APIs.
|
|
15
|
-
# x-openapi-flow describes how they actually work β for developers and AI.
|
|
15
|
+
# OpenAPI describes APIs. x-openapi-flow describes their workflows β for developers and AI.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
|
|
18
|
+
> Visualizing API lifecycle directly from your OpenAPI spec
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
`x-openapi-flow` adds a **declarative state machine** to your OpenAPI spec.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Model resource lifecycles, enforce valid transitions, and generate flow-aware artifacts for documentation, SDKs, and automation.
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
`x-openapi-flow` makes flows explicit, so teams can:
|
|
24
|
+
## Why This Exists
|
|
26
25
|
|
|
27
|
-
-
|
|
28
|
-
- Generate flow-aware docs and diagrams
|
|
29
|
-
- Build SDKs that reduce invalid API calls
|
|
26
|
+
Building APIs is cheap. Building **complex, multi-step APIs that teams actually use correctly** is hard.
|
|
30
27
|
|
|
31
|
-
|
|
28
|
+
Teams face recurring problems:
|
|
32
29
|
|
|
33
|
-
|
|
30
|
+
- π **Manual documentation is brittle** β OpenAPI specs are static, often out of sync with real workflows
|
|
31
|
+
- π€ **AI agents can hallucinate** β LLMs and code-generating agents may produce invalid calls if workflows are unclear or undocumented
|
|
32
|
+
- π€― **Workflows are confusing** β multi-step operations are hard to track for humans and AI agents
|
|
33
|
+
- β οΈ **Invalid calls slip through** β developers make mistakes because lifecycle rules arenβt enforced
|
|
34
|
+
- β±οΈ **Integration slows down** β SDKs, Postman collections, and docs need constant manual updates
|
|
35
|
+
- π‘οΈ **Hard to prevent errors in production** β without explicit lifecycle rules, invalid operations can reach live systems, causing outages or inconsistencies
|
|
34
36
|
|
|
35
|
-
## TL;DR / Quick Start
|
|
36
37
|
|
|
37
|
-
|
|
38
|
+
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**.
|
|
39
|
+
|
|
40
|
+
## What This Enables
|
|
41
|
+
|
|
42
|
+
Turn your OpenAPI spec into a single source of truth for API behavior:
|
|
43
|
+
- Visualize API lifecycles directly in [Swagger UI](#swagger-ui-demo) and [Redoc](#redoc-demo)
|
|
44
|
+
- Validate flows and state transitions in [CI pipelines](#cli-commands)
|
|
45
|
+
- Generate [lifecycle diagrams automatically](#mermaid-example) from your OpenAPI spec
|
|
46
|
+
- Build [SDKs](#sdk-generation) that understand and respect API workflows
|
|
47
|
+
- Export [Postman](#postman-demo) and [Insomnia](#insomnia-demo) collections organized by lifecycle
|
|
48
|
+
- 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
|
|
49
|
+
|
|
50
|
+
## Quick Start
|
|
51
|
+
|
|
52
|
+
Initialize flow support in your project:
|
|
38
53
|
|
|
39
54
|
```bash
|
|
40
55
|
npx x-openapi-flow init
|
|
41
56
|
```
|
|
42
|
-
or
|
|
43
|
-
```bash
|
|
44
|
-
npx x-openapi-flow apply openapi.x.yaml
|
|
45
|
-
```
|
|
46
57
|
|
|
47
|
-
|
|
58
|
+
After regenerating your OpenAPI file, apply and validate the flow (optional):
|
|
48
59
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
3. Run `apply` whenever the OpenAPI file is regenerated.
|
|
60
|
+
```bash
|
|
61
|
+
npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
|
|
52
62
|
|
|
53
|
-
|
|
63
|
+
npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality
|
|
64
|
+
```
|
|
54
65
|
|
|
55
|
-
|
|
56
|
-
- `{context}.flow.(json|yaml)`: generated OpenAPI output after merge (the file you validate and serve in docs/tools).
|
|
66
|
+
This will:
|
|
57
67
|
|
|
58
|
-
|
|
68
|
+
- enrich your OpenAPI spec with flow metadata
|
|
69
|
+
- validate lifecycle consistency
|
|
70
|
+
- catch invalid transitions early
|
|
59
71
|
|
|
60
|
-
|
|
61
|
-
2. run `apply`
|
|
62
|
-
3. validate/use `.flow`
|
|
72
|
+
π‘ Tip: run this in CI to enforce API workflow correctness
|
|
63
73
|
|
|
64
|
-
|
|
65
|
-
|
|
74
|
+
<a id="mermaid-example"></a>
|
|
75
|
+
### Real Lifecycle Example
|
|
66
76
|
|
|
67
|
-
|
|
77
|
+
Hereβs a real-world payment lifecycle represented in x-openapi-flow:
|
|
68
78
|
|
|
79
|
+
```
|
|
80
|
+
CREATED -> AUTHORIZED -> CAPTURED -> REFUNDED
|
|
81
|
+
```
|
|
69
82
|
|
|
70
|
-
|
|
83
|
+
Generate a visual graph of the lifecycle:
|
|
71
84
|
|
|
72
85
|
```bash
|
|
73
|
-
npx x-openapi-flow
|
|
86
|
+
npx x-openapi-flow graph openapi.flow.yaml --format mermaid
|
|
74
87
|
```
|
|
75
88
|
|
|
76
|
-
|
|
89
|
+
Resulting diagram:
|
|
77
90
|
|
|
78
|
-
```
|
|
79
|
-
|
|
91
|
+
```mermaid
|
|
92
|
+
graph TD
|
|
93
|
+
CREATED --> AUTHORIZED
|
|
94
|
+
AUTHORIZED --> CAPTURED
|
|
95
|
+
CAPTURED --> REFUNDED
|
|
80
96
|
```
|
|
81
97
|
|
|
98
|
+
> This visualization makes your API workflow explicit, easy to communicate, and ready for documentation or demos.
|
|
99
|
+
|
|
100
|
+
<a id="sdk-generation"></a>
|
|
101
|
+
## Generate Flow-Aware SDKs
|
|
102
|
+
|
|
103
|
+
Create a TypeScript SDK that **respects your APIβs lifecycle and transition rules**, following best practices seen in leading companies like **Stripe** and **Adyen**:
|
|
104
|
+
|
|
105
|
+
- **Orchestrator by model**: each resource exposes methods that enforce valid transitions
|
|
106
|
+
- **Chainable API calls**: perform sequences naturally and safely
|
|
107
|
+
|
|
82
108
|
```bash
|
|
83
|
-
npx x-openapi-flow
|
|
109
|
+
npx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk
|
|
84
110
|
```
|
|
85
111
|
|
|
86
|
-
|
|
112
|
+
Example usage:
|
|
87
113
|
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
114
|
+
```ts
|
|
115
|
+
const payment = await sdk.payments.create({ amount: 1000 });
|
|
116
|
+
await payment.authorize();
|
|
117
|
+
await payment.capture();
|
|
92
118
|
```
|
|
93
119
|
|
|
94
|
-
|
|
120
|
+
> This SDK guides developers through valid transition paths, following patterns used by market leaders to ensure safe and intuitive integrations.
|
|
121
|
+
|
|
122
|
+
## Who Benefits Most
|
|
123
|
+
|
|
124
|
+
x-openapi-flow is ideal for teams and organizations that want **clear, enforceable API workflows**:
|
|
125
|
+
|
|
126
|
+
- **API-first organizations** β maintain a single source of truth for API behavior
|
|
127
|
+
- **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
|
|
128
|
+
- **API platform teams** β ensure consistent lifecycle rules across endpoints
|
|
129
|
+
- **Companies with complex API workflows** β reduce errors and ambiguity in multi-step processes
|
|
130
|
+
- **SDK teams** β generate flow-aware SDKs that guide developers
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
## Why x-openapi-flow?
|
|
134
|
+
|
|
135
|
+
See how **x-openapi-flow extends OpenAPI** to make your API workflows explicit, enforceable, and actionable:
|
|
95
136
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
137
|
+
| Capability | OpenAPI | x-openapi-flow |
|
|
138
|
+
| --- | --- | --- |
|
|
139
|
+
| Endpoint contracts | β
Yes | β
Yes (fully compatible, extended) |
|
|
140
|
+
| Lifecycle states | β No | β
Yes β define states for each resource |
|
|
141
|
+
| Transition validation | β No | β
Yes β catch invalid calls before runtime |
|
|
142
|
+
| Flow diagrams | β No | β
Yes β generate visual lifecycle graphs |
|
|
143
|
+
| Usage guidance (next valid actions) | Limited/manual | β
Built-in via lifecycle metadata β guides developers and AI agents |
|
|
99
144
|
|
|
100
|
-
## Integration
|
|
145
|
+
## Integration Demos
|
|
101
146
|
|
|
102
|
-
|
|
147
|
+
Explore how x-openapi-flow integrates with popular API tools, making lifecycles and flows explicit for documentation and testing.
|
|
103
148
|
|
|
104
|
-
|
|
149
|
+
<a id="swagger-ui-demo"></a>
|
|
150
|
+
### Swagger UI β Visualize Flows in Your Docs
|
|
105
151
|
|
|
106
152
|
```bash
|
|
107
153
|
cd example/swagger-ui
|
|
@@ -110,21 +156,14 @@ npm run apply
|
|
|
110
156
|
npm start
|
|
111
157
|
```
|
|
112
158
|
|
|
113
|
-
Note: in this example, `npm run apply` prefers local sidecars (`swagger.x.yaml|yml|json`) and falls back to `examples/swagger.x.yaml|json` when a local sidecar is not present.
|
|
114
|
-
|
|
115
|
-
Experience outcome:
|
|
116
|
-
|
|
117
|
-
- operation docs enriched with `x-openapi-flow` fields
|
|
118
|
-
- visual lifecycle context while navigating endpoints
|
|
119
|
-
|
|
120
|
-
Demo media:
|
|
121
|
-
|
|
122
159
|
|
|
123
|
-
|
|
160
|
+
> Lifecycle panel shows valid states and transitions
|
|
124
161
|
|
|
125
|
-
|
|
162
|
+
|
|
163
|
+
> Detailed view of transitions per operation
|
|
126
164
|
|
|
127
|
-
|
|
165
|
+
<a id="redoc-demo"></a>
|
|
166
|
+
### Redoc β Flow-Aware Documentation
|
|
128
167
|
|
|
129
168
|
```bash
|
|
130
169
|
cd example/redoc
|
|
@@ -133,20 +172,13 @@ npm run apply
|
|
|
133
172
|
npm run generate
|
|
134
173
|
```
|
|
135
174
|
|
|
136
|
-
Experience outcome:
|
|
137
|
-
|
|
138
|
-
- portable `redoc-flow/` package with lifecycle panel
|
|
139
|
-
- stable documentation artifact for teams and portals
|
|
140
|
-
|
|
141
|
-
Demo media:
|
|
142
|
-
|
|
143
175
|
|
|
144
176
|
|
|
145
177
|
|
|
178
|
+
> Auto-generated lifecycle diagrams make documentation clear and consistent
|
|
146
179
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
Use this when you want collections aligned with lifecycle transitions.
|
|
180
|
+
<a id="postman-demo"></a>
|
|
181
|
+
### Postman β Organized API Collections
|
|
150
182
|
|
|
151
183
|
```bash
|
|
152
184
|
cd example/postman
|
|
@@ -155,19 +187,12 @@ npm run apply
|
|
|
155
187
|
npm run generate
|
|
156
188
|
```
|
|
157
189
|
|
|
158
|
-
Experience outcome:
|
|
159
|
-
|
|
160
|
-
- flow-oriented Postman collection
|
|
161
|
-
- request execution closer to real transition paths
|
|
162
|
-
|
|
163
|
-
Demo media:
|
|
164
|
-
|
|
165
190
|
|
|
166
191
|
|
|
192
|
+
> Collections reflect lifecycle order, reducing integration errors
|
|
167
193
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
Use this when your team runs API scenarios in Insomnia workspaces.
|
|
194
|
+
<a id="insomnia-demo"></a>
|
|
195
|
+
### Insomnia β Organized API Collections
|
|
171
196
|
|
|
172
197
|
```bash
|
|
173
198
|
cd example/insomnia
|
|
@@ -176,297 +201,116 @@ npm run apply
|
|
|
176
201
|
npm run generate
|
|
177
202
|
```
|
|
178
203
|
|
|
179
|
-
Experience outcome:
|
|
180
|
-
|
|
181
|
-
- generated workspace export with grouped lifecycle requests
|
|
182
|
-
- faster onboarding to operation prerequisites and flow order
|
|
183
|
-
|
|
184
|
-
Demo media:
|
|
185
|
-
|
|
186
204
|
|
|
187
205
|
|
|
206
|
+
> Requests are pre-organized according to lifecycle transitions
|
|
188
207
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
Use this when you want a generated flow-aware SDK for application integration.
|
|
192
|
-
|
|
193
|
-
```bash
|
|
194
|
-
cd example/sdk/typescript
|
|
195
|
-
npm install
|
|
196
|
-
npm run apply
|
|
197
|
-
npm run generate
|
|
198
|
-
npm run run:sample
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
Experience outcome:
|
|
202
|
-
|
|
203
|
-
- generated TypeScript SDK in `sdk/` from `x-openapi-flow` metadata
|
|
204
|
-
- minimal runnable sample showing typed SDK usage in `src/sample.ts`
|
|
205
|
-
- lifecycle-oriented methods and transition-aware resource instances
|
|
206
|
-
|
|
207
|
-
Example project:
|
|
208
|
-
|
|
209
|
-
- [example/sdk/typescript/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/example/sdk/typescript/README.md)
|
|
210
|
-
|
|
211
|
-
More integration details:
|
|
212
|
-
|
|
213
|
-
- [docs/wiki/integrations/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Swagger-UI-Integration.md)
|
|
214
|
-
- [docs/wiki/integrations/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Redoc-Integration.md)
|
|
215
|
-
- [docs/wiki/integrations/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Postman-Integration.md)
|
|
216
|
-
- [docs/wiki/integrations/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Insomnia-Integration.md)
|
|
217
|
-
|
|
218
|
-
---
|
|
219
|
-
|
|
220
|
-
## CLI in Practice (Server Workflow)
|
|
221
|
-
|
|
222
|
-
Use this sequence as your default lifecycle guardrail in backend projects:
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
# 1) Bootstrap sidecar from OpenAPI source
|
|
226
|
-
npx x-openapi-flow init
|
|
227
|
-
|
|
228
|
-
# 2) Merge sidecar into flow-aware OpenAPI output
|
|
229
|
-
npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
|
|
230
|
-
|
|
231
|
-
# 3) Detect drift before commit
|
|
232
|
-
npx x-openapi-flow diff openapi.yaml --format pretty
|
|
233
|
-
|
|
234
|
-
# 4) Enforce lifecycle quality gates
|
|
235
|
-
npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality
|
|
236
|
-
npx x-openapi-flow lint openapi.flow.yaml
|
|
237
|
-
|
|
238
|
-
# 5) Generate graph artifact for PR discussion
|
|
239
|
-
npx x-openapi-flow graph openapi.flow.yaml --format mermaid
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
CLI quick references for daily usage:
|
|
243
|
-
|
|
244
|
-
```bash
|
|
245
|
-
npx x-openapi-flow help [command]
|
|
246
|
-
npx x-openapi-flow <command> --help
|
|
247
|
-
npx x-openapi-flow <command> --verbose
|
|
248
|
-
npx x-openapi-flow completion [bash|zsh]
|
|
249
|
-
```
|
|
208
|
+
<a id="cli-commands"></a>
|
|
209
|
+
## CLI Reference β Common Commands
|
|
250
210
|
|
|
251
|
-
|
|
211
|
+
Use x-openapi-flow from the command line to **manage, validate, visualize, and generate SDKs/docs for your API workflows**.
|
|
252
212
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
Generate a flow-aware SDK directly from your OpenAPI + `x-openapi-flow` metadata:
|
|
213
|
+
### General
|
|
256
214
|
|
|
257
215
|
```bash
|
|
258
|
-
npx x-openapi-flow
|
|
259
|
-
```
|
|
216
|
+
npx x-openapi-flow help [command] # show help for a specific command
|
|
260
217
|
|
|
261
|
-
|
|
218
|
+
npx x-openapi-flow --help # general help
|
|
262
219
|
|
|
263
|
-
|
|
264
|
-
- operation transition awareness (`next_operation_id`, prerequisites, propagated fields)
|
|
265
|
-
- reusable client layer for application services
|
|
220
|
+
npx x-openapi-flow version # show version
|
|
266
221
|
|
|
267
|
-
|
|
222
|
+
npx x-openapi-flow doctor [--config path] # check setup and config
|
|
268
223
|
|
|
269
|
-
|
|
270
|
-
import { FlowApiClient } from "./sdk/src";
|
|
271
|
-
|
|
272
|
-
const api = new FlowApiClient({ baseUrl: process.env.API_BASE_URL });
|
|
273
|
-
|
|
274
|
-
const payment = await api.payments.create({ amount: 1000 });
|
|
275
|
-
await payment.authorize();
|
|
276
|
-
await payment.capture();
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
---
|
|
280
|
-
|
|
281
|
-
## Example: Payment Flow
|
|
282
|
-
|
|
283
|
-
```mermaid
|
|
284
|
-
graph TD
|
|
285
|
-
CreatePayment --> AuthorizePayment
|
|
286
|
-
AuthorizePayment --> CapturePayment
|
|
287
|
-
CapturePayment --> RefundPayment
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
### Flow-aware SDK Example (TypeScript)
|
|
291
|
-
|
|
292
|
-
```ts
|
|
293
|
-
const payment = await sdk.payments.create({ amount: 1000 });
|
|
294
|
-
await payment.authorize();
|
|
295
|
-
await payment.capture();
|
|
296
|
-
await payment.refund();
|
|
224
|
+
npx x-openapi-flow completion [bash|zsh] # enable shell autocompletion
|
|
297
225
|
```
|
|
298
226
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
## Installation
|
|
304
|
-
|
|
305
|
-
Install from npm (default):
|
|
227
|
+
### Workflow Management
|
|
306
228
|
|
|
307
229
|
```bash
|
|
308
|
-
|
|
309
|
-
|
|
230
|
+
# initialize flow support
|
|
231
|
+
npx x-openapi-flow init [--flows path] [--force] [--dry-run]
|
|
310
232
|
|
|
311
|
-
|
|
233
|
+
# apply flows to OpenAPI
|
|
234
|
+
npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]
|
|
312
235
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
npm install @tiago-marques/x-openapi-flow
|
|
236
|
+
# validate transitions
|
|
237
|
+
npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality]
|
|
316
238
|
```
|
|
317
239
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
```ini
|
|
321
|
-
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
Use a GitHub PAT with `read:packages` (install) and `write:packages` (publish).
|
|
325
|
-
|
|
326
|
-
---
|
|
327
|
-
|
|
328
|
-
## CLI Reference (Selected Commands)
|
|
240
|
+
### Visualization & Documentation
|
|
329
241
|
|
|
330
242
|
```bash
|
|
331
|
-
|
|
332
|
-
npx x-openapi-flow --
|
|
333
|
-
npx x-openapi-flow version
|
|
334
|
-
npx x-openapi-flow --version
|
|
335
|
-
npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality]
|
|
336
|
-
npx x-openapi-flow init [--flows path] [--force] [--dry-run]
|
|
337
|
-
npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]
|
|
338
|
-
npx x-openapi-flow analyze [openapi-file] [--format pretty|json] [--out path] [--merge] [--flows path]
|
|
339
|
-
npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
|
|
340
|
-
npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
|
|
341
|
-
npx x-openapi-flow generate-redoc [openapi-file] [--output path]
|
|
342
|
-
<!-- Demo media removed -->
|
|
343
|
-
npx x-openapi-flow doctor [--config path]
|
|
344
|
-
npx x-openapi-flow completion [bash|zsh]
|
|
345
|
-
```
|
|
243
|
+
# generate lifecycle diagrams
|
|
244
|
+
npx x-openapi-flow graph [openapi-file] [--format mermaid|json]
|
|
346
245
|
|
|
347
|
-
|
|
246
|
+
# generate Redoc docs
|
|
247
|
+
npx x-openapi-flow generate-redoc [openapi-file] [--output path]
|
|
348
248
|
|
|
349
|
-
|
|
350
|
-
npx x-openapi-flow
|
|
249
|
+
# export flows
|
|
250
|
+
npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
|
|
351
251
|
```
|
|
352
252
|
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
- [docs/wiki/reference/CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/CLI-Reference.md)
|
|
356
|
-
- [x-openapi-flow/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/README.md)
|
|
357
|
-
|
|
358
|
-
---
|
|
359
|
-
|
|
360
|
-
<!-- Demo media removed -->
|
|
361
|
-
|
|
362
|
-
- Auto-detects OpenAPI source files (`openapi.yaml`, `openapi.json`, `swagger.yaml`, etc.)
|
|
363
|
-
- Creates or syncs `{context}.x.(json|yaml)` (sidecar with lifecycle metadata)
|
|
364
|
-
- Generates `{context}.flow.(json|yaml)` automatically when missing
|
|
365
|
-
- In interactive mode, asks before recreating existing flow files
|
|
366
|
-
- In non-interactive mode, requires `--force` to recreate when flow file already exists
|
|
367
|
-
|
|
368
|
-
Recommended quality gate:
|
|
253
|
+
### SDK Generation
|
|
369
254
|
|
|
370
255
|
```bash
|
|
371
|
-
|
|
256
|
+
# generate flow-aware SDK
|
|
257
|
+
npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
|
|
372
258
|
```
|
|
373
259
|
|
|
374
|
-
|
|
260
|
+
Full details:
|
|
375
261
|
|
|
376
|
-
|
|
262
|
+
- [CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/CLI-Reference.md)
|
|
263
|
+
- [README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/README.md)
|
|
377
264
|
|
|
378
|
-
|
|
379
|
-
<!-- Demo media removed -->
|
|
380
|
-
- Schema contract correctness
|
|
381
|
-
- Orphan states
|
|
382
|
-
- Initial/terminal state structure
|
|
383
|
-
- Cycles and unreachable states
|
|
384
|
-
- Quality findings (duplicate transitions, invalid refs, non-terminating states)
|
|
265
|
+
## Documentation and Guides
|
|
385
266
|
|
|
386
|
-
|
|
267
|
+
Get the most out of x-openapi-flow with detailed guides, examples, and integration instructions:
|
|
387
268
|
|
|
388
|
-
|
|
269
|
+
- **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)
|
|
270
|
+
Learn how to introduce x-openapi-flow into your API workflow efficiently
|
|
389
271
|
|
|
390
|
-
-
|
|
391
|
-
|
|
392
|
-
- Postman and Insomnia: generated lifecycle-aware collections/workspaces
|
|
393
|
-
- SDK generator: TypeScript available, other languages planned
|
|
272
|
+
- **Troubleshooting** β [docs/wiki/reference/Troubleshooting.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Troubleshooting.md)
|
|
273
|
+
Quick solutions to common issues and validation errors
|
|
394
274
|
|
|
395
|
-
|
|
396
|
-
|
|
275
|
+
- **Real Examples** β [docs/wiki/engineering/Real-Examples.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/Real-Examples.md)
|
|
276
|
+
Explore real OpenAPI specs enhanced with lifecycle metadata
|
|
397
277
|
|
|
398
|
-
-
|
|
399
|
-
|
|
400
|
-
|
|
278
|
+
- **Integrations**:
|
|
279
|
+
- **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)
|
|
280
|
+
See flow-aware panels in Swagger UI
|
|
281
|
+
- **Redoc** β [docs/wiki/integrations/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Redoc-Integration.md)
|
|
282
|
+
Generate lifecycle diagrams in Redoc documentation
|
|
283
|
+
- **Postman** β [docs/wiki/integrations/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Postman-Integration.md)
|
|
284
|
+
Organize collections according to valid transitions
|
|
285
|
+
- **Insomnia** β [docs/wiki/integrations/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Insomnia-Integration.md)
|
|
286
|
+
Pre-configure requests according to lifecycle flows
|
|
401
287
|
|
|
402
|
-
|
|
288
|
+
## Roadmap
|
|
403
289
|
|
|
404
|
-
|
|
290
|
+
Weβre actively expanding x-openapi-flow to support multiple platforms and SDKs. Check our progress:
|
|
405
291
|
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
3. `apply`
|
|
409
|
-
4. `validate --profile strict`
|
|
292
|
+
- π **Roadmap Overview** β [#2](https://github.com/tiago-marques/x-openapi-flow/issues/2)
|
|
293
|
+
See planned features and high-level goals
|
|
410
294
|
|
|
411
|
-
|
|
295
|
+
- π **Python SDK MVP** β [#3](https://github.com/tiago-marques/x-openapi-flow/issues/3)
|
|
296
|
+
Enable Python developers to use flow-aware SDKs
|
|
412
297
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
Populate {context}.x.(json|yaml) per operationId with coherent lifecycle states and transitions,
|
|
416
|
-
including next_operation_id, prerequisite_field_refs, and propagated_field_refs when applicable.
|
|
417
|
-
Do not change endpoint paths or HTTP methods.
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
---
|
|
421
|
-
|
|
422
|
-
## Regeneration Workflow
|
|
423
|
-
|
|
424
|
-
```bash
|
|
425
|
-
# 1) Generate or update OpenAPI source
|
|
426
|
-
# 2) Initialize sidecar metadata
|
|
427
|
-
npx x-openapi-flow init
|
|
428
|
-
# 3) Edit {context}.x.(json|yaml)
|
|
429
|
-
# 4) Re-apply after each OpenAPI regeneration
|
|
430
|
-
npx x-openapi-flow apply openapi.x.yaml
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
---
|
|
434
|
-
|
|
435
|
-
## Included Examples
|
|
298
|
+
- π **Go SDK MVP** β [#4](https://github.com/tiago-marques/x-openapi-flow/issues/4)
|
|
299
|
+
Bring lifecycle-aware SDKs to Go projects
|
|
436
300
|
|
|
437
|
-
-
|
|
438
|
-
|
|
439
|
-
- `ticket-api.yaml` (support)
|
|
440
|
-
- `quality-warning-api.yaml` (quality warnings)
|
|
441
|
-
- `non-terminating-api.yaml` (non-terminating states)
|
|
442
|
-
|
|
443
|
-
More examples: [docs/wiki/engineering/Real-Examples.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/Real-Examples.md)
|
|
444
|
-
|
|
445
|
-
---
|
|
446
|
-
|
|
447
|
-
## Repository Structure
|
|
448
|
-
|
|
449
|
-
- [x-openapi-flow/schema/flow-schema.json](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/schema/flow-schema.json): extension JSON Schema contract
|
|
450
|
-
- [x-openapi-flow/lib/validator.js](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/lib/validator.js): schema + graph validation engine
|
|
451
|
-
- [x-openapi-flow/bin/x-openapi-flow.js](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/bin/x-openapi-flow.js): CLI entrypoint
|
|
452
|
-
- `x-openapi-flow/examples/*.yaml`: sample OpenAPI files
|
|
453
|
-
- [.github/workflows/x-openapi-flow-validate.yml](https://github.com/tiago-marques/x-openapi-flow/blob/main/.github/workflows/x-openapi-flow-validate.yml): CI validation example
|
|
454
|
-
|
|
455
|
-
---
|
|
301
|
+
- β **Kotlin SDK MVP** β [#5](https://github.com/tiago-marques/x-openapi-flow/issues/5)
|
|
302
|
+
Support Android and JVM developers with flow-aware SDKs
|
|
456
303
|
|
|
457
304
|
## Changelog
|
|
458
305
|
|
|
459
|
-
|
|
460
|
-
Release notes: [docs/wiki/releases/RELEASE_NOTES_v1.4.0.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/releases/RELEASE_NOTES_v1.4.0.md)
|
|
461
|
-
|
|
462
|
-
---
|
|
306
|
+
Keep track of updates and improvements in x-openapi-flow:
|
|
463
307
|
|
|
464
|
-
|
|
308
|
+
- **Version History** β [CHANGELOG.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/CHANGELOG.md)
|
|
309
|
+
Review the full version history and past updates
|
|
465
310
|
|
|
466
|
-
|
|
311
|
+
- **Release Notes** β [docs/wiki/releases/RELEASE_NOTES_v1.4.0.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/releases/RELEASE_NOTES_v1.4.0.md)
|
|
312
|
+
See detailed notes for the latest release, including new features and fixes
|
|
467
313
|
|
|
468
|
-
|
|
469
|
-
- Wiki pages
|
|
470
|
-
- Release notes and changelog entries
|
|
314
|
+
## Documentation Language Policy
|
|
471
315
|
|
|
472
|
-
|
|
316
|
+
To 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.
|