x-openapi-flow 1.1.0
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/LICENSE +21 -0
- package/README.md +48 -0
- package/bin/x-openapi-flow.js +461 -0
- package/examples/non-terminating-api.yaml +70 -0
- package/examples/order-api.yaml +111 -0
- package/examples/payment-api.yaml +114 -0
- package/examples/quality-warning-api.yaml +66 -0
- package/examples/ticket-api.yaml +115 -0
- package/lib/validator.js +712 -0
- package/package.json +49 -0
- package/schema/flow-schema.json +68 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
openapi: "3.0.3"
|
|
2
|
+
info:
|
|
3
|
+
title: Payment API
|
|
4
|
+
version: "1.0.0"
|
|
5
|
+
description: >
|
|
6
|
+
Simple payment API demonstrating the x-flow extension for OpenAPI Spec.
|
|
7
|
+
|
|
8
|
+
paths:
|
|
9
|
+
/payments:
|
|
10
|
+
post:
|
|
11
|
+
summary: Create and authorize a payment
|
|
12
|
+
operationId: createPayment
|
|
13
|
+
x-flow:
|
|
14
|
+
version: "1.0"
|
|
15
|
+
id: create-payment-flow
|
|
16
|
+
current_state: AUTHORIZED
|
|
17
|
+
description: A payment is created and immediately authorized.
|
|
18
|
+
idempotency:
|
|
19
|
+
header: Idempotency-Key
|
|
20
|
+
required: true
|
|
21
|
+
transitions:
|
|
22
|
+
- target_state: CAPTURED
|
|
23
|
+
condition: Merchant explicitly requests capture.
|
|
24
|
+
trigger_type: synchronous
|
|
25
|
+
requestBody:
|
|
26
|
+
required: true
|
|
27
|
+
content:
|
|
28
|
+
application/json:
|
|
29
|
+
schema:
|
|
30
|
+
$ref: "#/components/schemas/PaymentRequest"
|
|
31
|
+
responses:
|
|
32
|
+
"201":
|
|
33
|
+
description: Payment created and authorized successfully.
|
|
34
|
+
content:
|
|
35
|
+
application/json:
|
|
36
|
+
schema:
|
|
37
|
+
$ref: "#/components/schemas/Payment"
|
|
38
|
+
"400":
|
|
39
|
+
description: Invalid request payload.
|
|
40
|
+
"422":
|
|
41
|
+
description: Payment authorization failed.
|
|
42
|
+
|
|
43
|
+
/payments/{id}/capture:
|
|
44
|
+
post:
|
|
45
|
+
summary: Capture an authorized payment
|
|
46
|
+
operationId: capturePayment
|
|
47
|
+
x-flow:
|
|
48
|
+
version: "1.0"
|
|
49
|
+
id: capture-payment-flow
|
|
50
|
+
current_state: CAPTURED
|
|
51
|
+
description: Captures a previously authorized payment, moving funds to the merchant.
|
|
52
|
+
idempotency:
|
|
53
|
+
header: Idempotency-Key
|
|
54
|
+
required: true
|
|
55
|
+
parameters:
|
|
56
|
+
- name: id
|
|
57
|
+
in: path
|
|
58
|
+
required: true
|
|
59
|
+
schema:
|
|
60
|
+
type: string
|
|
61
|
+
description: Unique identifier of the payment to capture.
|
|
62
|
+
responses:
|
|
63
|
+
"200":
|
|
64
|
+
description: Payment captured successfully.
|
|
65
|
+
content:
|
|
66
|
+
application/json:
|
|
67
|
+
schema:
|
|
68
|
+
$ref: "#/components/schemas/Payment"
|
|
69
|
+
"404":
|
|
70
|
+
description: Payment not found.
|
|
71
|
+
"409":
|
|
72
|
+
description: Payment is not in a capturable state.
|
|
73
|
+
|
|
74
|
+
components:
|
|
75
|
+
schemas:
|
|
76
|
+
PaymentRequest:
|
|
77
|
+
type: object
|
|
78
|
+
required:
|
|
79
|
+
- amount
|
|
80
|
+
- currency
|
|
81
|
+
properties:
|
|
82
|
+
amount:
|
|
83
|
+
type: integer
|
|
84
|
+
description: Amount in the smallest currency unit (e.g. cents).
|
|
85
|
+
example: 1000
|
|
86
|
+
currency:
|
|
87
|
+
type: string
|
|
88
|
+
description: ISO 4217 currency code.
|
|
89
|
+
example: USD
|
|
90
|
+
description:
|
|
91
|
+
type: string
|
|
92
|
+
description: Human-readable description of the payment.
|
|
93
|
+
example: "Order #1234"
|
|
94
|
+
|
|
95
|
+
Payment:
|
|
96
|
+
type: object
|
|
97
|
+
properties:
|
|
98
|
+
id:
|
|
99
|
+
type: string
|
|
100
|
+
description: Unique identifier of the payment.
|
|
101
|
+
example: pay_abc123
|
|
102
|
+
amount:
|
|
103
|
+
type: integer
|
|
104
|
+
example: 1000
|
|
105
|
+
currency:
|
|
106
|
+
type: string
|
|
107
|
+
example: USD
|
|
108
|
+
state:
|
|
109
|
+
type: string
|
|
110
|
+
description: Current lifecycle state of the payment.
|
|
111
|
+
example: AUTHORIZED
|
|
112
|
+
created_at:
|
|
113
|
+
type: string
|
|
114
|
+
format: date-time
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
openapi: "3.0.3"
|
|
2
|
+
info:
|
|
3
|
+
title: Quality Warning API
|
|
4
|
+
version: "1.0.0"
|
|
5
|
+
description: >
|
|
6
|
+
Example API intentionally crafted to trigger quality warnings.
|
|
7
|
+
|
|
8
|
+
paths:
|
|
9
|
+
/a/start:
|
|
10
|
+
post:
|
|
11
|
+
summary: Start flow A
|
|
12
|
+
operationId: startA
|
|
13
|
+
x-flow:
|
|
14
|
+
version: "1.0"
|
|
15
|
+
id: start-a-flow
|
|
16
|
+
current_state: A_START
|
|
17
|
+
transitions:
|
|
18
|
+
- target_state: A_DONE
|
|
19
|
+
condition: Flow A completes.
|
|
20
|
+
trigger_type: synchronous
|
|
21
|
+
- target_state: A_DONE
|
|
22
|
+
condition: Duplicate transition used for quality warning demo.
|
|
23
|
+
trigger_type: synchronous
|
|
24
|
+
responses:
|
|
25
|
+
"200":
|
|
26
|
+
description: Started flow A.
|
|
27
|
+
|
|
28
|
+
/a/done:
|
|
29
|
+
post:
|
|
30
|
+
summary: Complete flow A
|
|
31
|
+
operationId: doneA
|
|
32
|
+
x-flow:
|
|
33
|
+
version: "1.0"
|
|
34
|
+
id: done-a-flow
|
|
35
|
+
current_state: A_DONE
|
|
36
|
+
responses:
|
|
37
|
+
"200":
|
|
38
|
+
description: Flow A finished.
|
|
39
|
+
|
|
40
|
+
/b/start:
|
|
41
|
+
post:
|
|
42
|
+
summary: Start flow B
|
|
43
|
+
operationId: startB
|
|
44
|
+
x-flow:
|
|
45
|
+
version: "1.0"
|
|
46
|
+
id: start-b-flow
|
|
47
|
+
current_state: B_START
|
|
48
|
+
transitions:
|
|
49
|
+
- target_state: B_DONE
|
|
50
|
+
condition: Flow B completes.
|
|
51
|
+
trigger_type: webhook
|
|
52
|
+
responses:
|
|
53
|
+
"200":
|
|
54
|
+
description: Started flow B.
|
|
55
|
+
|
|
56
|
+
/b/done:
|
|
57
|
+
post:
|
|
58
|
+
summary: Complete flow B
|
|
59
|
+
operationId: doneB
|
|
60
|
+
x-flow:
|
|
61
|
+
version: "1.0"
|
|
62
|
+
id: done-b-flow
|
|
63
|
+
current_state: B_DONE
|
|
64
|
+
responses:
|
|
65
|
+
"200":
|
|
66
|
+
description: Flow B finished.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
openapi: "3.0.3"
|
|
2
|
+
info:
|
|
3
|
+
title: Support Ticket API
|
|
4
|
+
version: "1.0.0"
|
|
5
|
+
description: >
|
|
6
|
+
Example API demonstrating x-flow for support ticket lifecycle.
|
|
7
|
+
|
|
8
|
+
paths:
|
|
9
|
+
/tickets:
|
|
10
|
+
post:
|
|
11
|
+
summary: Open a support ticket
|
|
12
|
+
operationId: openTicket
|
|
13
|
+
x-flow:
|
|
14
|
+
version: "1.0"
|
|
15
|
+
id: open-ticket-flow
|
|
16
|
+
current_state: OPEN
|
|
17
|
+
description: Ticket has been opened by a customer.
|
|
18
|
+
transitions:
|
|
19
|
+
- target_state: IN_PROGRESS
|
|
20
|
+
condition: Agent starts handling the ticket.
|
|
21
|
+
trigger_type: synchronous
|
|
22
|
+
responses:
|
|
23
|
+
"201":
|
|
24
|
+
description: Ticket created.
|
|
25
|
+
|
|
26
|
+
/tickets/{id}/start:
|
|
27
|
+
post:
|
|
28
|
+
summary: Start ticket handling
|
|
29
|
+
operationId: startTicket
|
|
30
|
+
x-flow:
|
|
31
|
+
version: "1.0"
|
|
32
|
+
id: start-ticket-flow
|
|
33
|
+
current_state: IN_PROGRESS
|
|
34
|
+
description: Ticket is actively being worked on.
|
|
35
|
+
transitions:
|
|
36
|
+
- target_state: WAITING_CUSTOMER
|
|
37
|
+
condition: Agent needs more information from customer.
|
|
38
|
+
trigger_type: synchronous
|
|
39
|
+
- target_state: RESOLVED
|
|
40
|
+
condition: Issue fixed by agent.
|
|
41
|
+
trigger_type: synchronous
|
|
42
|
+
parameters:
|
|
43
|
+
- name: id
|
|
44
|
+
in: path
|
|
45
|
+
required: true
|
|
46
|
+
schema:
|
|
47
|
+
type: string
|
|
48
|
+
responses:
|
|
49
|
+
"200":
|
|
50
|
+
description: Ticket moved to in-progress.
|
|
51
|
+
|
|
52
|
+
/tickets/{id}/wait-customer:
|
|
53
|
+
post:
|
|
54
|
+
summary: Wait for customer response
|
|
55
|
+
operationId: waitCustomer
|
|
56
|
+
x-flow:
|
|
57
|
+
version: "1.0"
|
|
58
|
+
id: wait-customer-flow
|
|
59
|
+
current_state: WAITING_CUSTOMER
|
|
60
|
+
description: System is waiting for customer follow-up.
|
|
61
|
+
transitions:
|
|
62
|
+
- target_state: RESOLVED
|
|
63
|
+
condition: Customer provides requested information and agent confirms resolution.
|
|
64
|
+
trigger_type: webhook
|
|
65
|
+
parameters:
|
|
66
|
+
- name: id
|
|
67
|
+
in: path
|
|
68
|
+
required: true
|
|
69
|
+
schema:
|
|
70
|
+
type: string
|
|
71
|
+
responses:
|
|
72
|
+
"200":
|
|
73
|
+
description: Ticket moved to waiting customer.
|
|
74
|
+
|
|
75
|
+
/tickets/{id}/resolve:
|
|
76
|
+
post:
|
|
77
|
+
summary: Resolve ticket
|
|
78
|
+
operationId: resolveTicket
|
|
79
|
+
x-flow:
|
|
80
|
+
version: "1.0"
|
|
81
|
+
id: resolve-ticket-flow
|
|
82
|
+
current_state: RESOLVED
|
|
83
|
+
description: Ticket has a proposed solution.
|
|
84
|
+
transitions:
|
|
85
|
+
- target_state: CLOSED
|
|
86
|
+
condition: Customer confirms issue is solved.
|
|
87
|
+
trigger_type: polling
|
|
88
|
+
parameters:
|
|
89
|
+
- name: id
|
|
90
|
+
in: path
|
|
91
|
+
required: true
|
|
92
|
+
schema:
|
|
93
|
+
type: string
|
|
94
|
+
responses:
|
|
95
|
+
"200":
|
|
96
|
+
description: Ticket resolved.
|
|
97
|
+
|
|
98
|
+
/tickets/{id}/close:
|
|
99
|
+
post:
|
|
100
|
+
summary: Close ticket
|
|
101
|
+
operationId: closeTicket
|
|
102
|
+
x-flow:
|
|
103
|
+
version: "1.0"
|
|
104
|
+
id: close-ticket-flow
|
|
105
|
+
current_state: CLOSED
|
|
106
|
+
description: Terminal state for the support flow.
|
|
107
|
+
parameters:
|
|
108
|
+
- name: id
|
|
109
|
+
in: path
|
|
110
|
+
required: true
|
|
111
|
+
schema:
|
|
112
|
+
type: string
|
|
113
|
+
responses:
|
|
114
|
+
"200":
|
|
115
|
+
description: Ticket closed.
|