Generate both OperatorService and WorkflowService API docs

temporalio · Feb 23, 2024 · d93898f · d93898f
1 parent 8427af8
commit d93898f
Show file tree

Hide file tree

Showing 3 changed files with 290 additions and 19 deletions.
diff --git a/Makefile b/Makefile
@@ -57,23 +57,29 @@ go-grpc: clean $(PROTO_OUT)
 		-I $(PROTO_ROOT) \
 		-p go-grpc_out=$(PROTO_PATHS) \
 		-p grpc-gateway_out=allow_patch_feature=false,$(PROTO_PATHS) \
-		-p doc_out=html,index.html,source_relative:$(PROTO_OUT) \
-		-p openapi_out=$(OAPI_OUT) \
-		-p openapi_opt=enum_type=string \
-		-p openapiv2_out=openapi \
-        -p openapiv2_opt=allow_merge=true,merge_file_name=openapiv2,simple_operation_ids=true
+		-p doc_out=html,index.html,source_relative:$(PROTO_OUT)
 
 fix-path:
 	mv -f $(PROTO_OUT)/temporal/api/* $(PROTO_OUT) && rm -rf $(PROTO_OUT)/temporal
 
 # We need to rewrite bits of this to support our shorthand payload format
 # We use both yq and jq here as they preserve comments and the ordering of the original
 # document
-http-api-docs: go-grpc
+
+http-api-docs:
+	protoc -I $(PROTO_ROOT) \
+		--openapi_out=$(OAPI_OUT) \
+		--openapi_opt=enum_type=string \
+		--openapiv2_out=openapi \
+        --openapiv2_opt=allow_merge=true,merge_file_name=openapiv2,simple_operation_ids=true \
+		temporal/api/workflowservice/v1/* \
+		temporal/api/operatorservice/v1/*
+
 	jq --rawfile desc $(OAPI_OUT)/payload_description.txt < $(OAPI_OUT)/openapiv2.swagger.json '.definitions.v1Payload={description: $$desc}' > $(OAPI_OUT)/v2.tmp
 	mv -f $(OAPI_OUT)/v2.tmp $(OAPI_OUT)/openapiv2.json
 	rm -f $(OAPI_OUT)/openapiv2.swagger.json
 	DESC=$$(cat $(OAPI_OUT)/payload_description.txt) yq e -i '$(OAPIV3_PATH).description = strenv(DESC) | del($(OAPI3_PATH).type) | del($(OAPI3_PATH).properties)' $(OAPI_OUT)/openapi.yaml
+# TODO: remove operationId prefixes from yaml
 	mv $(OAPI_OUT)/openapi.yaml $(OAPI_OUT)/openapiv3.yaml
 
 ##### Plugins & tools #####

diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json
@@ -7,6 +7,9 @@
   "tags": [
     {
       "name": "WorkflowService"
+    },
+    {
+      "name": "OperatorService"
     }
   ],
   "consumes": [
@@ -1028,6 +1031,37 @@
         ]
       }
     },
+    "/api/v1/namespaces/{namespace}/search-attributes": {
+      "get": {
+        "summary": "ListSearchAttributes returns comprehensive information about search attributes.",
+        "operationId": "ListSearchAttributes",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v1ListSearchAttributesResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "namespace",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "tags": [
+          "OperatorService"
+        ]
+      }
+    },
     "/api/v1/namespaces/{namespace}/task-queues/{taskQueue.name}": {
       "get": {
         "summary": "DescribeTaskQueue returns information about the target task queue.",
@@ -3126,6 +3160,12 @@
       },
       "title": "Represents the identifier used by a activity author to define the activity. Typically, the\nname of a function. This is sometimes referred to as the activity's \"name\""
     },
+    "v1AddOrUpdateRemoteClusterResponse": {
+      "type": "object"
+    },
+    "v1AddSearchAttributesResponse": {
+      "type": "object"
+    },
     "v1Alert": {
       "type": "object",
       "properties": {
@@ -3709,6 +3749,37 @@
         }
       }
     },
+    "v1ClusterMetadata": {
+      "type": "object",
+      "properties": {
+        "clusterName": {
+          "type": "string",
+          "description": "Name of the cluster name."
+        },
+        "clusterId": {
+          "type": "string",
+          "description": "Id of the cluster."
+        },
+        "address": {
+          "type": "string",
+          "description": "Cluster accessible address."
+        },
+        "initialFailoverVersion": {
+          "type": "string",
+          "format": "int64",
+          "description": "A unique failover version across all connected clusters."
+        },
+        "historyShardCount": {
+          "type": "integer",
+          "format": "int32",
+          "description": "History service shard number."
+        },
+        "isConnectionEnabled": {
+          "type": "boolean",
+          "description": "A flag to indicate if a connection is active."
+        }
+      }
+    },
     "v1ClusterReplicationConfig": {
       "type": "object",
       "properties": {
@@ -3902,6 +3973,15 @@
         }
       }
     },
+    "v1CreateOrUpdateNexusIncomingServiceResponse": {
+      "type": "object",
+      "properties": {
+        "service": {
+          "$ref": "#/definitions/v1IncomingService",
+          "description": "Data post acceptance. Can be used to issue additional updates to this record."
+        }
+      }
+    },
     "v1CreateScheduleResponse": {
       "type": "object",
       "properties": {
@@ -3923,6 +4003,18 @@
         }
       }
     },
+    "v1DeleteNamespaceResponse": {
+      "type": "object",
+      "properties": {
+        "deletedNamespace": {
+          "type": "string",
+          "description": "Temporary namespace name that is used during reclaim resources step."
+        }
+      }
+    },
+    "v1DeleteNexusIncomingServiceResponse": {
+      "type": "object"
+    },
     "v1DeleteScheduleResponse": {
       "type": "object"
     },
@@ -4254,6 +4346,14 @@
       },
       "description": "GetClusterInfoResponse contains information about Temporal cluster."
     },
+    "v1GetNexusIncomingServiceResponse": {
+      "type": "object",
+      "properties": {
+        "service": {
+          "$ref": "#/definitions/v1IncomingService"
+        }
+      }
+    },
     "v1GetSearchAttributesResponse": {
       "type": "object",
       "properties": {
@@ -4605,6 +4705,36 @@
       ],
       "default": "HISTORY_EVENT_FILTER_TYPE_UNSPECIFIED"
     },
+    "v1IncomingService": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "format": "int64",
+          "description": "Data version for this service. Must match current version on update or set to 0 to create a new service."
+        },
+        "name": {
+          "type": "string",
+          "description": "Service name, unique for this cluster.\nThe service name is used to address this service.\nBy default, when using Nexus over HTTP, the service name is matched against the base URL path.\nE.g. the URL /my-service would match a service named \"my-service\".\nThe name can contain any characters and is escaped when matched against a URL."
+        },
+        "namespace": {
+          "type": "string",
+          "description": "Namespace to route requests to."
+        },
+        "taskQueue": {
+          "type": "string",
+          "description": "Task queue to route requests to."
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/protobufAny"
+          },
+          "description": "Generic service metadata that is available to the server's authorizer."
+        }
+      },
+      "description": "A binding from a service name to namespace, task queue, and metadata for dispatching incoming Nexus requests."
+    },
     "v1IndexedValueType": {
       "type": "string",
       "enum": [
@@ -4697,6 +4827,23 @@
         }
       }
     },
+    "v1ListClustersResponse": {
+      "type": "object",
+      "properties": {
+        "clusters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1ClusterMetadata"
+          },
+          "title": "List of all cluster information"
+        },
+        "nextPageToken": {
+          "type": "string",
+          "format": "byte"
+        }
+      }
+    },
     "v1ListNamespacesResponse": {
       "type": "object",
       "properties": {
@@ -4713,6 +4860,23 @@
         }
       }
     },
+    "v1ListNexusIncomingServicesResponse": {
+      "type": "object",
+      "properties": {
+        "nextPageToken": {
+          "type": "string",
+          "format": "byte",
+          "description": "Token for getting the next page."
+        },
+        "services": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1IncomingService"
+          }
+        }
+      }
+    },
     "v1ListOpenWorkflowExecutionsResponse": {
       "type": "object",
       "properties": {
@@ -4757,6 +4921,32 @@
         }
       }
     },
+    "v1ListSearchAttributesResponse": {
+      "type": "object",
+      "properties": {
+        "customAttributes": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/v1IndexedValueType"
+          },
+          "description": "Mapping between custom (user-registered) search attribute name to its IndexedValueType."
+        },
+        "systemAttributes": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/v1IndexedValueType"
+          },
+          "description": "Mapping between system (predefined) search attribute name to its IndexedValueType."
+        },
+        "storageSchema": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Mapping from the attribute name to the visibility storage native type."
+        }
+      }
+    },
     "v1ListTaskQueuePartitionsResponse": {
       "type": "object",
       "properties": {
@@ -5607,6 +5797,12 @@
       },
       "description": "ReleaseInfo contains information about specific version of temporal."
     },
+    "v1RemoveRemoteClusterResponse": {
+      "type": "object"
+    },
+    "v1RemoveSearchAttributesResponse": {
+      "type": "object"
+    },
     "v1ReplicationState": {
       "type": "string",
       "enum": [