x-openapi-flow 1.4.0 β 1.4.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 +151 -329
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,98 +10,126 @@
|
|
|
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
|
-
Most teams document endpoints but not lifecycle behavior. State transitions become implicit, inconsistent, and hard to validate in CI.
|
|
25
|
-
`x-openapi-flow` makes flows explicit, so teams can:
|
|
26
24
|
|
|
27
|
-
|
|
28
|
-
- Generate flow-aware docs and diagrams
|
|
29
|
-
- Build SDKs that reduce invalid API calls
|
|
25
|
+
## What This Enables
|
|
30
26
|
|
|
31
|
-
|
|
27
|
+
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/Insomnia collections organized by lifecycle
|
|
33
|
+
- Create AI-ready API contracts for agentic integrations
|
|
32
34
|
|
|
33
|
-
|
|
35
|
+
## Quick Start
|
|
34
36
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
From your API project root:
|
|
37
|
+
Initialize flow support in your project:
|
|
38
38
|
|
|
39
39
|
```bash
|
|
40
40
|
npx x-openapi-flow init
|
|
41
41
|
```
|
|
42
|
-
or
|
|
43
|
-
```bash
|
|
44
|
-
npx x-openapi-flow apply openapi.x.yaml
|
|
45
|
-
```
|
|
46
42
|
|
|
47
|
-
|
|
43
|
+
After regenerating your OpenAPI file, apply and validate the flow (optional):
|
|
48
44
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
3. Run `apply` whenever the OpenAPI file is regenerated.
|
|
45
|
+
```bash
|
|
46
|
+
npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
|
|
52
47
|
|
|
53
|
-
|
|
48
|
+
npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality
|
|
49
|
+
```
|
|
54
50
|
|
|
55
|
-
|
|
56
|
-
- `{context}.flow.(json|yaml)`: generated OpenAPI output after merge (the file you validate and serve in docs/tools).
|
|
51
|
+
This will:
|
|
57
52
|
|
|
58
|
-
|
|
53
|
+
- enrich your OpenAPI spec with flow metadata
|
|
54
|
+
- validate lifecycle consistency
|
|
55
|
+
- catch invalid transitions early
|
|
59
56
|
|
|
60
|
-
|
|
61
|
-
2. run `apply`
|
|
62
|
-
3. validate/use `.flow`
|
|
57
|
+
π‘ Tip: run this in CI to enforce API workflow correctness
|
|
63
58
|
|
|
64
|
-
|
|
65
|
-
Troubleshooting: [docs/wiki/reference/Troubleshooting.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Troubleshooting.md)
|
|
59
|
+
### Real Lifecycle Example
|
|
66
60
|
|
|
67
|
-
|
|
61
|
+
Hereβs a real-world payment lifecycle represented in x-openapi-flow:
|
|
68
62
|
|
|
63
|
+
```
|
|
64
|
+
CREATED -> AUTHORIZED -> CAPTURED -> REFUNDED
|
|
65
|
+
```
|
|
69
66
|
|
|
70
|
-
|
|
67
|
+
Generate a visual graph of the lifecycle:
|
|
71
68
|
|
|
72
69
|
```bash
|
|
73
|
-
npx x-openapi-flow
|
|
70
|
+
npx x-openapi-flow graph openapi.flow.yaml --format mermaid
|
|
74
71
|
```
|
|
75
72
|
|
|
76
|
-
|
|
73
|
+
Resulting diagram:
|
|
77
74
|
|
|
78
|
-
```
|
|
79
|
-
|
|
75
|
+
```mermaid
|
|
76
|
+
graph TD
|
|
77
|
+
CREATED --> AUTHORIZED
|
|
78
|
+
AUTHORIZED --> CAPTURED
|
|
79
|
+
CAPTURED --> REFUNDED
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
+
> This visualization makes your API workflow explicit, easy to communicate, and ready for documentation or demos.
|
|
83
|
+
|
|
84
|
+
## Generate Flow-Aware SDKs
|
|
85
|
+
|
|
86
|
+
Create a TypeScript SDK that **respects your APIβs lifecycle and transition rules**, following best practices seen in leading companies like **Stripe** and **Adyen**:
|
|
87
|
+
|
|
88
|
+
- **Orchestrator by model**: each resource exposes methods that enforce valid transitions
|
|
89
|
+
- **Chainable API calls**: perform sequences naturally and safely
|
|
90
|
+
|
|
82
91
|
```bash
|
|
83
|
-
npx x-openapi-flow
|
|
92
|
+
npx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk
|
|
84
93
|
```
|
|
85
94
|
|
|
86
|
-
|
|
95
|
+
Example usage:
|
|
87
96
|
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
97
|
+
```ts
|
|
98
|
+
const payment = await sdk.payments.create({ amount: 1000 });
|
|
99
|
+
await payment.authorize();
|
|
100
|
+
await payment.capture();
|
|
92
101
|
```
|
|
93
102
|
|
|
94
|
-
|
|
103
|
+
> This SDK guides developers through valid transition paths, following patterns used by market leaders to ensure safe and intuitive integrations.
|
|
95
104
|
|
|
96
|
-
|
|
97
|
-
- explicit transition contracts instead of implicit tribal knowledge
|
|
98
|
-
- safer API evolution with fewer integration regressions
|
|
105
|
+
## Who Benefits Most
|
|
99
106
|
|
|
100
|
-
|
|
107
|
+
x-openapi-flow is ideal for teams and organizations that want **clear, enforceable API workflows**:
|
|
101
108
|
|
|
102
|
-
|
|
109
|
+
- **API-first organizations** β maintain a single source of truth for API behavior
|
|
110
|
+
- **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
|
|
111
|
+
- **API platform teams** β ensure consistent lifecycle rules across endpoints
|
|
112
|
+
- **Companies with complex API workflows** β reduce errors and ambiguity in multi-step processes
|
|
113
|
+
- **SDK teams** β generate flow-aware SDKs that guide developers
|
|
103
114
|
|
|
104
|
-
|
|
115
|
+
|
|
116
|
+
## Why x-openapi-flow?
|
|
117
|
+
|
|
118
|
+
See how **x-openapi-flow extends OpenAPI** to make your API workflows explicit, enforceable, and actionable:
|
|
119
|
+
|
|
120
|
+
| Capability | OpenAPI | x-openapi-flow |
|
|
121
|
+
| --- | --- | --- |
|
|
122
|
+
| Endpoint contracts | β
Yes | β
Yes (fully compatible, extended) |
|
|
123
|
+
| Lifecycle states | β No | β
Yes β define states for each resource |
|
|
124
|
+
| Transition validation | β No | β
Yes β catch invalid calls before runtime |
|
|
125
|
+
| Flow diagrams | β No | β
Yes β generate visual lifecycle graphs |
|
|
126
|
+
| Usage guidance (next valid actions) | Limited/manual | β
Built-in via lifecycle metadata β guides developers and AI agents |
|
|
127
|
+
|
|
128
|
+
## Integration Demos
|
|
129
|
+
|
|
130
|
+
Explore how x-openapi-flow integrates with popular API tools, making lifecycles and flows explicit for documentation and testing.
|
|
131
|
+
|
|
132
|
+
### Swagger UI β Visualize Flows in Your Docs
|
|
105
133
|
|
|
106
134
|
```bash
|
|
107
135
|
cd example/swagger-ui
|
|
@@ -110,21 +138,13 @@ npm run apply
|
|
|
110
138
|
npm start
|
|
111
139
|
```
|
|
112
140
|
|
|
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
141
|
|
|
123
|
-
|
|
142
|
+
> Lifecycle panel shows valid states and transitions
|
|
124
143
|
|
|
125
|
-
|
|
144
|
+
|
|
145
|
+
> Detailed view of transitions per operation
|
|
126
146
|
|
|
127
|
-
|
|
147
|
+
### Redoc β Flow-Aware Documentation
|
|
128
148
|
|
|
129
149
|
```bash
|
|
130
150
|
cd example/redoc
|
|
@@ -133,20 +153,12 @@ npm run apply
|
|
|
133
153
|
npm run generate
|
|
134
154
|
```
|
|
135
155
|
|
|
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
156
|
|
|
144
157
|
|
|
145
158
|
|
|
159
|
+
> Auto-generated lifecycle diagrams make documentation clear and consistent
|
|
146
160
|
|
|
147
|
-
### Postman
|
|
148
|
-
|
|
149
|
-
Use this when you want collections aligned with lifecycle transitions.
|
|
161
|
+
### Postman β Organized API Collections
|
|
150
162
|
|
|
151
163
|
```bash
|
|
152
164
|
cd example/postman
|
|
@@ -155,19 +167,11 @@ npm run apply
|
|
|
155
167
|
npm run generate
|
|
156
168
|
```
|
|
157
169
|
|
|
158
|
-
Experience outcome:
|
|
159
|
-
|
|
160
|
-
- flow-oriented Postman collection
|
|
161
|
-
- request execution closer to real transition paths
|
|
162
|
-
|
|
163
|
-
Demo media:
|
|
164
|
-
|
|
165
170
|
|
|
166
171
|
|
|
172
|
+
> Collections reflect lifecycle order, reducing integration errors
|
|
167
173
|
|
|
168
|
-
### Insomnia
|
|
169
|
-
|
|
170
|
-
Use this when your team runs API scenarios in Insomnia workspaces.
|
|
174
|
+
### Insomnia β Organized API Collections
|
|
171
175
|
|
|
172
176
|
```bash
|
|
173
177
|
cd example/insomnia
|
|
@@ -176,297 +180,115 @@ npm run apply
|
|
|
176
180
|
npm run generate
|
|
177
181
|
```
|
|
178
182
|
|
|
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
183
|
|
|
187
184
|
|
|
185
|
+
> Requests are pre-organized according to lifecycle transitions
|
|
188
186
|
|
|
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)
|
|
187
|
+
## CLI Reference β Common Commands
|
|
210
188
|
|
|
211
|
-
|
|
189
|
+
Use x-openapi-flow from the command line to **manage, validate, visualize, and generate SDKs/docs for your API workflows**.
|
|
212
190
|
|
|
213
|
-
|
|
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:
|
|
191
|
+
### General
|
|
223
192
|
|
|
224
193
|
```bash
|
|
225
|
-
#
|
|
226
|
-
npx x-openapi-flow init
|
|
194
|
+
npx x-openapi-flow help [command] # show help for a specific command
|
|
227
195
|
|
|
228
|
-
|
|
229
|
-
npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
|
|
196
|
+
npx x-openapi-flow --help # general help
|
|
230
197
|
|
|
231
|
-
|
|
232
|
-
npx x-openapi-flow diff openapi.yaml --format pretty
|
|
198
|
+
npx x-openapi-flow version # show version
|
|
233
199
|
|
|
234
|
-
#
|
|
235
|
-
npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality
|
|
236
|
-
npx x-openapi-flow lint openapi.flow.yaml
|
|
200
|
+
npx x-openapi-flow doctor [--config path] # check setup and config
|
|
237
201
|
|
|
238
|
-
|
|
239
|
-
npx x-openapi-flow graph openapi.flow.yaml --format mermaid
|
|
202
|
+
npx x-openapi-flow completion [bash|zsh] # enable shell autocompletion
|
|
240
203
|
```
|
|
241
204
|
|
|
242
|
-
|
|
205
|
+
### Workflow Management
|
|
243
206
|
|
|
244
207
|
```bash
|
|
245
|
-
|
|
246
|
-
npx x-openapi-flow
|
|
247
|
-
npx x-openapi-flow <command> --verbose
|
|
248
|
-
npx x-openapi-flow completion [bash|zsh]
|
|
249
|
-
```
|
|
208
|
+
# initialize flow support
|
|
209
|
+
npx x-openapi-flow init [--flows path] [--force] [--dry-run]
|
|
250
210
|
|
|
251
|
-
|
|
211
|
+
# apply flows to OpenAPI
|
|
212
|
+
npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]
|
|
252
213
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
Generate a flow-aware SDK directly from your OpenAPI + `x-openapi-flow` metadata:
|
|
256
|
-
|
|
257
|
-
```bash
|
|
258
|
-
npx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
What you get:
|
|
262
|
-
|
|
263
|
-
- resource-centric classes with lifecycle-safe methods
|
|
264
|
-
- operation transition awareness (`next_operation_id`, prerequisites, propagated fields)
|
|
265
|
-
- reusable client layer for application services
|
|
266
|
-
|
|
267
|
-
Typical integration snippet:
|
|
268
|
-
|
|
269
|
-
```ts
|
|
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
|
|
214
|
+
# validate transitions
|
|
215
|
+
npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality]
|
|
288
216
|
```
|
|
289
217
|
|
|
290
|
-
###
|
|
291
|
-
|
|
292
|
-
```ts
|
|
293
|
-
const payment = await sdk.payments.create({ amount: 1000 });
|
|
294
|
-
await payment.authorize();
|
|
295
|
-
await payment.capture();
|
|
296
|
-
await payment.refund();
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
At each stage, only valid lifecycle actions should be available.
|
|
300
|
-
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
## Installation
|
|
304
|
-
|
|
305
|
-
Install from npm (default):
|
|
218
|
+
### Visualization & Documentation
|
|
306
219
|
|
|
307
220
|
```bash
|
|
308
|
-
|
|
309
|
-
|
|
221
|
+
# generate lifecycle diagrams
|
|
222
|
+
npx x-openapi-flow graph [openapi-file] [--format mermaid|json]
|
|
310
223
|
|
|
311
|
-
|
|
224
|
+
# generate Redoc docs
|
|
225
|
+
npx x-openapi-flow generate-redoc [openapi-file] [--output path]
|
|
312
226
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
npm install @tiago-marques/x-openapi-flow
|
|
227
|
+
# export flows
|
|
228
|
+
npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
|
|
316
229
|
```
|
|
317
230
|
|
|
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)
|
|
231
|
+
### SDK Generation
|
|
329
232
|
|
|
330
233
|
```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]
|
|
234
|
+
# generate flow-aware SDK
|
|
235
|
+
npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
|
|
345
236
|
```
|
|
346
237
|
|
|
347
|
-
|
|
238
|
+
Full details:
|
|
348
239
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
```
|
|
240
|
+
- [CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/CLI-Reference.md)
|
|
241
|
+
- [README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/README.md)
|
|
352
242
|
|
|
353
|
-
|
|
243
|
+
## Documentation and Guides
|
|
354
244
|
|
|
355
|
-
|
|
356
|
-
- [x-openapi-flow/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/README.md)
|
|
245
|
+
Get the most out of x-openapi-flow with detailed guides, examples, and integration instructions:
|
|
357
246
|
|
|
358
|
-
|
|
247
|
+
- **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)
|
|
248
|
+
Learn how to introduce x-openapi-flow into your API workflow efficiently
|
|
359
249
|
|
|
360
|
-
|
|
250
|
+
- **Troubleshooting** β [docs/wiki/reference/Troubleshooting.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Troubleshooting.md)
|
|
251
|
+
Quick solutions to common issues and validation errors
|
|
361
252
|
|
|
362
|
-
-
|
|
363
|
-
|
|
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:
|
|
369
|
-
|
|
370
|
-
```bash
|
|
371
|
-
npx x-openapi-flow validate openapi.yaml --profile strict
|
|
372
|
-
```
|
|
253
|
+
- **Real Examples** β [docs/wiki/engineering/Real-Examples.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/Real-Examples.md)
|
|
254
|
+
Explore real OpenAPI specs enhanced with lifecycle metadata
|
|
373
255
|
|
|
374
|
-
|
|
256
|
+
- **Integrations**:
|
|
257
|
+
- **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)
|
|
258
|
+
See flow-aware panels in Swagger UI
|
|
259
|
+
- **Redoc** β [docs/wiki/integrations/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Redoc-Integration.md)
|
|
260
|
+
Generate lifecycle diagrams in Redoc documentation
|
|
261
|
+
- **Postman** β [docs/wiki/integrations/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Postman-Integration.md)
|
|
262
|
+
Organize collections according to valid transitions
|
|
263
|
+
- **Insomnia** β [docs/wiki/integrations/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Insomnia-Integration.md)
|
|
264
|
+
Pre-configure requests according to lifecycle flows
|
|
375
265
|
|
|
376
|
-
##
|
|
266
|
+
## Roadmap
|
|
377
267
|
|
|
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)
|
|
268
|
+
Weβre actively expanding x-openapi-flow to support multiple platforms and SDKs. Check our progress:
|
|
385
269
|
|
|
386
|
-
|
|
270
|
+
- π **Roadmap Overview** β [#2](https://github.com/tiago-marques/x-openapi-flow/issues/2)
|
|
271
|
+
See planned features and high-level goals
|
|
387
272
|
|
|
388
|
-
|
|
273
|
+
- π **Python SDK MVP** β [#3](https://github.com/tiago-marques/x-openapi-flow/issues/3)
|
|
274
|
+
Enable Python developers to use flow-aware SDKs
|
|
389
275
|
|
|
390
|
-
-
|
|
391
|
-
-
|
|
392
|
-
- Postman and Insomnia: generated lifecycle-aware collections/workspaces
|
|
393
|
-
- SDK generator: TypeScript available, other languages planned
|
|
394
|
-
|
|
395
|
-
<!-- Demo media removed -->
|
|
396
|
-
Integration docs:
|
|
397
|
-
|
|
398
|
-
- [docs/wiki/integrations/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Swagger-UI-Integration.md)
|
|
399
|
-
---
|
|
400
|
-
## Copilot Ready (AI Sidecar Authoring)
|
|
401
|
-
|
|
402
|
-
Use [llm.txt](https://github.com/tiago-marques/x-openapi-flow/blob/main/llm.txt) as authoring guidance for sidecar population.
|
|
403
|
-
|
|
404
|
-
Typical AI-assisted loop:
|
|
405
|
-
|
|
406
|
-
1. `init`
|
|
407
|
-
2. AI fills `{context}.x.(json|yaml)`
|
|
408
|
-
3. `apply`
|
|
409
|
-
4. `validate --profile strict`
|
|
410
|
-
|
|
411
|
-
Prompt template:
|
|
412
|
-
|
|
413
|
-
```text
|
|
414
|
-
Use llm.txt from this repository as authoring rules.
|
|
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
|
-
```
|
|
276
|
+
- π **Go SDK MVP** β [#4](https://github.com/tiago-marques/x-openapi-flow/issues/4)
|
|
277
|
+
Bring lifecycle-aware SDKs to Go projects
|
|
419
278
|
|
|
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
|
|
436
|
-
|
|
437
|
-
- `payment-api.yaml` (financial)
|
|
438
|
-
- `order-api.yaml` (e-commerce/logistics)
|
|
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
|
-
---
|
|
279
|
+
- β **Kotlin SDK MVP** β [#5](https://github.com/tiago-marques/x-openapi-flow/issues/5)
|
|
280
|
+
Support Android and JVM developers with flow-aware SDKs
|
|
456
281
|
|
|
457
282
|
## Changelog
|
|
458
283
|
|
|
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
|
-
---
|
|
284
|
+
Keep track of updates and improvements in x-openapi-flow:
|
|
463
285
|
|
|
464
|
-
|
|
286
|
+
- **Version History** β [CHANGELOG.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/CHANGELOG.md)
|
|
287
|
+
Review the full version history and past updates
|
|
465
288
|
|
|
466
|
-
|
|
289
|
+
- **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)
|
|
290
|
+
See detailed notes for the latest release, including new features and fixes
|
|
467
291
|
|
|
468
|
-
|
|
469
|
-
- Wiki pages
|
|
470
|
-
- Release notes and changelog entries
|
|
292
|
+
## Documentation Language Policy
|
|
471
293
|
|
|
472
|
-
|
|
294
|
+
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.
|