Skip to content

Commit 3efc9b1

Browse files
yimincyiminc
committed
Update OpenAPI docs
1 parent 8225ef1 commit 3efc9b1

File tree

2 files changed

+58
-34
lines changed

2 files changed

+58
-34
lines changed

‎openapi/openapiv2.json‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3106,7 +3106,7 @@
31063106
},
31073107
"/api/v1/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/reset": {
31083108
"post": {
3109-
"summary": "ResetWorkflowExecution will reset an existing workflow execution to a specified\n`WORKFLOW_TASK_COMPLETED` event (exclusive). It will immediately terminate the current\nexecution instance.\nTODO: Does exclusive here mean *just* the completed event, or also WFT started? Otherwise the task is doomed to time out?",
3109+
"summary": "ResetWorkflowExecution will reset an existing workflow execution to a specified\n`WORKFLOW_TASK_COMPLETED` event (exclusive). It will immediately terminate the current\nexecution instance. \"Exclusive\" means the identified completed event itself is not replayed\nin the reset history; the preceding `WORKFLOW_TASK_STARTED` event remains and will be marked as failed\nimmediately, and a new workflow task will be scheduled to retry it.",
31103110
"operationId": "ResetWorkflowExecution2",
31113111
"responses": {
31123112
"200": {
@@ -6931,7 +6931,7 @@
69316931
},
69326932
"/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/reset": {
69336933
"post": {
6934-
"summary": "ResetWorkflowExecution will reset an existing workflow execution to a specified\n`WORKFLOW_TASK_COMPLETED` event (exclusive). It will immediately terminate the current\nexecution instance.\nTODO: Does exclusive here mean *just* the completed event, or also WFT started? Otherwise the task is doomed to time out?",
6934+
"summary": "ResetWorkflowExecution will reset an existing workflow execution to a specified\n`WORKFLOW_TASK_COMPLETED` event (exclusive). It will immediately terminate the current\nexecution instance. \"Exclusive\" means the identified completed event itself is not replayed\nin the reset history; the preceding `WORKFLOW_TASK_STARTED` event remains and will be marked as failed\nimmediately, and a new workflow task will be scheduled to retry it.",
69356935
"operationId": "ResetWorkflowExecution",
69366936
"responses": {
69376937
"200": {
@@ -9630,7 +9630,7 @@
96309630
},
96319631
"requestId": {
96329632
"type": "string",
9633-
"title": "TODO ??"
9633+
"description": "This field is populated from the RecordActivityTaskStartedRequest. Matching service would\nset the request_id on the RecordActivityTaskStartedRequest to a new UUID. This is useful\nin case a RecordActivityTaskStarted call succeed but matching doesn't get that response,\nso matching could retry and history service would return success if the request_id matches.\nIn that case, matching will continue to deliver the task to worker. Without this field, history\nservice would return AlreadyStarted error, and matching would drop the task."
96349634
},
96359635
"attempt": {
96369636
"type": "integer",
@@ -11700,12 +11700,12 @@
1170011700
"version": {
1170111701
"type": "string",
1170211702
"format": "int64",
11703-
"title": "TODO: What is this? Appears unused by SDKs"
11703+
"description": "Failover version of the event, used by the server for multi-cluster replication and history\nversioning. SDKs generally ignore this field."
1170411704
},
1170511705
"taskId": {
1170611706
"type": "string",
1170711707
"format": "int64",
11708-
"title": "TODO: What is this? Appears unused by SDKs"
11708+
"description": "Identifier used by the service to order replication and transfer tasks associated with this\nevent. SDKs generally ignore this field."
1170911709
},
1171011710
"workerMayIgnore": {
1171111711
"type": "boolean",
@@ -15288,7 +15288,7 @@
1528815288
"description": "Free-form comment describing the intention of this spec."
1528915289
}
1529015290
},
15291-
"title": "StructuredCalendarSpec describes an event specification relative to the\ncalendar, in a form that's easy to work with programmatically. Each field can\nbe one or more ranges.\nA timestamp matches if at least one range of each field matches the\ncorresponding fields of the timestamp, except for year: if year is missing,\nthat means all years match. For all fields besides year, at least one Range\nmust be present to match anything.\nTODO: add relative-to-end-of-month\nTODO: add nth day-of-week in month"
15291+
"description": "StructuredCalendarSpec describes an event specification relative to the\ncalendar, in a form that's easy to work with programmatically. Each field can\nbe one or more ranges.\nA timestamp matches if at least one range of each field matches the\ncorresponding fields of the timestamp, except for year: if year is missing,\nthat means all years match. For all fields besides year, at least one Range\nmust be present to match anything.\nRelative expressions such as \"last day of the month\" or \"third Monday\" are not currently\nrepresentable; callers must enumerate the concrete days they require."
1529215292
},
1529315293
"v1TaskIdBlock": {
1529415294
"type": "object",
@@ -16499,12 +16499,12 @@
1649916499
"properties": {
1650016500
"cause": {
1650116501
"type": "string",
16502-
"title": "User provided reason for requesting cancellation\nTODO: shall we create a new field with name \"reason\" and deprecate this one?"
16502+
"title": "User provided reason for requesting cancellation"
1650316503
},
1650416504
"externalInitiatedEventId": {
1650516505
"type": "string",
1650616506
"format": "int64",
16507-
"title": "TODO: Is this the ID of the event in the workflow which initiated this cancel, if there was one?"
16507+
"description": "The ID of the `REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED` event in the external\nworkflow history when the cancellation was requested by another workflow."
1650816508
},
1650916509
"externalWorkflowExecution": {
1651016510
"$ref": "#/definitions/v1WorkflowExecution"
@@ -16598,18 +16598,18 @@
1659816598
},
1659916599
"backoffStartInterval": {
1660016600
"type": "string",
16601-
"title": "TODO: How and is this used?"
16601+
"description": "How long the server will wait before scheduling the first workflow task for the new run.\nUsed for cron, retry, and other continue-as-new cases that server may enforce some minimal\ndelay between new runs for system protection purpose."
1660216602
},
1660316603
"initiator": {
1660416604
"$ref": "#/definitions/v1ContinueAsNewInitiator"
1660516605
},
1660616606
"failure": {
1660716607
"$ref": "#/definitions/apifailurev1Failure",
16608-
"description": "TODO: David are these right?\nDeprecated. If a workflow's retry policy would cause a new run to start when the current one\nhas failed, this field would be populated with that failure. Now (when supported by server\nand sdk) the final event will be `WORKFLOW_EXECUTION_FAILED` with `new_execution_run_id` set."
16608+
"description": "Deprecated. If a workflow's retry policy would cause a new run to start when the current one\nhas failed, this field would be populated with that failure. Now (when supported by server\nand sdk) the final event will be `WORKFLOW_EXECUTION_FAILED` with `new_execution_run_id` set."
1660916609
},
1661016610
"lastCompletionResult": {
1661116611
"$ref": "#/definitions/v1Payloads",
16612-
"title": "TODO: Is this the result of *this* workflow as it continued-as-new?"
16612+
"description": "The result from the most recent completed run of this workflow. The SDK surfaces this to the\nnew run via APIs such as `GetLastCompletionResult`."
1661316613
},
1661416614
"header": {
1661516615
"$ref": "#/definitions/v1Header"
@@ -17485,7 +17485,7 @@
1748517485
},
1748617486
"identity": {
1748717487
"type": "string",
17488-
"title": "If a worker explicitly failed this task, it's identity. TODO: What is this set to if server fails the task?"
17488+
"description": "If a worker explicitly failed this task, this field contains the worker's identity. \nWhen the server generates the failure internally this field is set as 'history-service'."
1748917489
},
1749017490
"baseRunId": {
1749117491
"type": "string",
@@ -17498,7 +17498,7 @@
1749817498
"forkEventVersion": {
1749917499
"type": "string",
1750017500
"format": "int64",
17501-
"title": "TODO: ?"
17501+
"description": "Version of the event where the history branch was forked. Used by multi-cluster replication\nduring resets to identify the correct history branch."
1750217502
},
1750317503
"binaryChecksum": {
1750417504
"type": "string",
@@ -17542,7 +17542,7 @@
1754217542
},
1754317543
"requestId": {
1754417544
"type": "string",
17545-
"title": "TODO: ? Appears unused?"
17545+
"description": "This field is populated from the RecordWorkflowTaskStartedRequest. Matching service would\nset the request_id on the RecordWorkflowTaskStartedRequest to a new UUID. This is useful\nin case a RecordWorkflowTaskStarted call succeed but matching doesn't get that response,\nso matching could retry and history service would return success if the request_id matches.\nIn that case, matching will continue to deliver the task to worker. Without this field, history\nservice would return AlreadyStarted error, and matching would drop the task."
1754617546
},
1754717547
"suggestContinueAsNew": {
1754817548
"type": "boolean",

‎openapi/openapiv3.yaml‎

Lines changed: 44 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2882,8 +2882,9 @@ paths:
28822882
description: |-
28832883
ResetWorkflowExecution will reset an existing workflow execution to a specified
28842884
`WORKFLOW_TASK_COMPLETED` event (exclusive). It will immediately terminate the current
2885-
execution instance.
2886-
TODO: Does exclusive here mean *just* the completed event, or also WFT started? Otherwise the task is doomed to time out?
2885+
execution instance. "Exclusive" means the identified completed event itself is not replayed
2886+
in the reset history; the preceding `WORKFLOW_TASK_STARTED` event remains and will be marked as failed
2887+
immediately, and a new workflow task will be scheduled to retry it.
28872888
operationId: ResetWorkflowExecution
28882889
parameters:
28892890
- name: namespace
@@ -6306,8 +6307,9 @@ paths:
63066307
description: |-
63076308
ResetWorkflowExecution will reset an existing workflow execution to a specified
63086309
`WORKFLOW_TASK_COMPLETED` event (exclusive). It will immediately terminate the current
6309-
execution instance.
6310-
TODO: Does exclusive here mean *just* the completed event, or also WFT started? Otherwise the task is doomed to time out?
6310+
execution instance. "Exclusive" means the identified completed event itself is not replayed
6311+
in the reset history; the preceding `WORKFLOW_TASK_STARTED` event remains and will be marked as failed
6312+
immediately, and a new workflow task will be scheduled to retry it.
63116313
operationId: ResetWorkflowExecution
63126314
parameters:
63136315
- name: namespace
@@ -6775,7 +6777,13 @@ components:
67756777
description: id of the worker that picked up this task
67766778
requestId:
67776779
type: string
6778-
description: TODO ??
6780+
description: |-
6781+
This field is populated from the RecordActivityTaskStartedRequest. Matching service would
6782+
set the request_id on the RecordActivityTaskStartedRequest to a new UUID. This is useful
6783+
in case a RecordActivityTaskStarted call succeed but matching doesn't get that response,
6784+
so matching could retry and history service would return success if the request_id matches.
6785+
In that case, matching will continue to deliver the task to worker. Without this field, history
6786+
service would return AlreadyStarted error, and matching would drop the task.
67796787
attempt:
67806788
type: integer
67816789
description: Starting at 1, the number of times this task has been attempted
@@ -8666,10 +8674,14 @@ components:
86668674
format: enum
86678675
version:
86688676
type: string
8669-
description: 'TODO: What is this? Appears unused by SDKs'
8677+
description: |-
8678+
Failover version of the event, used by the server for multi-cluster replication and history
8679+
versioning. SDKs generally ignore this field.
86708680
taskId:
86718681
type: string
8672-
description: 'TODO: What is this? Appears unused by SDKs'
8682+
description: |-
8683+
Identifier used by the service to order replication and transfer tasks associated with this
8684+
event. SDKs generally ignore this field.
86738685
workerMayIgnore:
86748686
type: boolean
86758687
description: |-
@@ -12303,8 +12315,8 @@ components:
1230312315
corresponding fields of the timestamp, except for year: if year is missing,
1230412316
that means all years match. For all fields besides year, at least one Range
1230512317
must be present to match anything.
12306-
TODO: add relative-to-end-of-month
12307-
TODO: add nth day-of-week in month
12318+
Relative expressions such as "last day of the month" or "third Monday" are not currently
12319+
representable; callers must enumerate the concrete days they require.
1230812320
TaskIdBlock:
1230912321
type: object
1231012322
properties:
@@ -13942,12 +13954,12 @@ components:
1394213954
properties:
1394313955
cause:
1394413956
type: string
13945-
description: |-
13946-
User provided reason for requesting cancellation
13947-
TODO: shall we create a new field with name "reason" and deprecate this one?
13957+
description: User provided reason for requesting cancellation
1394813958
externalInitiatedEventId:
1394913959
type: string
13950-
description: 'TODO: Is this the ID of the event in the workflow which initiated this cancel, if there was one?'
13960+
description: |-
13961+
The ID of the `REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED` event in the external
13962+
workflow history when the cancellation was requested by another workflow.
1395113963
externalWorkflowExecution:
1395213964
$ref: '#/components/schemas/WorkflowExecution'
1395313965
identity:
@@ -14018,7 +14030,10 @@ components:
1401814030
backoffStartInterval:
1401914031
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
1402014032
type: string
14021-
description: 'TODO: How and is this used?'
14033+
description: |-
14034+
How long the server will wait before scheduling the first workflow task for the new run.
14035+
Used for cron, retry, and other continue-as-new cases that server may enforce some minimal
14036+
delay between new runs for system protection purpose.
1402214037
initiator:
1402314038
enum:
1402414039
- CONTINUE_AS_NEW_INITIATOR_UNSPECIFIED
@@ -14031,14 +14046,15 @@ components:
1403114046
allOf:
1403214047
- $ref: '#/components/schemas/Failure'
1403314048
description: |-
14034-
TODO: David are these right?
14035-
Deprecated. If a workflow's retry policy would cause a new run to start when the current one
14049+
Deprecated. If a workflow's retry policy would cause a new run to start when the current one
1403614050
has failed, this field would be populated with that failure. Now (when supported by server
1403714051
and sdk) the final event will be `WORKFLOW_EXECUTION_FAILED` with `new_execution_run_id` set.
1403814052
lastCompletionResult:
1403914053
allOf:
1404014054
- $ref: '#/components/schemas/Payloads'
14041-
description: 'TODO: Is this the result of *this* workflow as it continued-as-new?'
14055+
description: |-
14056+
The result from the most recent completed run of this workflow. The SDK surfaces this to the
14057+
new run via APIs such as `GetLastCompletionResult`.
1404214058
header:
1404314059
$ref: '#/components/schemas/Header'
1404414060
memo:
@@ -15027,7 +15043,7 @@ components:
1502715043
description: The failure details
1502815044
identity:
1502915045
type: string
15030-
description: 'If a worker explicitly failed this task, it''s identity. TODO: What is this set to if server fails the task?'
15046+
description: "If a worker explicitly failed this task, this field contains the worker's identity. \n When the server generates the failure internally this field is set as 'history-service'."
1503115047
baseRunId:
1503215048
type: string
1503315049
description: The original run id of the workflow. For reset workflow.
@@ -15036,7 +15052,9 @@ components:
1503615052
description: If the workflow is being reset, the new run id.
1503715053
forkEventVersion:
1503815054
type: string
15039-
description: 'TODO: ?'
15055+
description: |-
15056+
Version of the event where the history branch was forked. Used by multi-cluster replication
15057+
during resets to identify the correct history branch.
1504015058
binaryChecksum:
1504115059
type: string
1504215060
description: |-
@@ -15080,7 +15098,13 @@ components:
1508015098
description: Identity of the worker who picked up this task
1508115099
requestId:
1508215100
type: string
15083-
description: 'TODO: ? Appears unused?'
15101+
description: |-
15102+
This field is populated from the RecordWorkflowTaskStartedRequest. Matching service would
15103+
set the request_id on the RecordWorkflowTaskStartedRequest to a new UUID. This is useful
15104+
in case a RecordWorkflowTaskStarted call succeed but matching doesn't get that response,
15105+
so matching could retry and history service would return success if the request_id matches.
15106+
In that case, matching will continue to deliver the task to worker. Without this field, history
15107+
service would return AlreadyStarted error, and matching would drop the task.
1508415108
suggestContinueAsNew:
1508515109
type: boolean
1508615110
description: |-

0 commit comments

Comments
 (0)