rest: define openapi scheam for transaction execution

crates/sui-rest-api/openapi/openapi.json

@@ -469,7 +469,76 @@
           }
         }
       },
-      "post": {}
+      "post": {
+        "tags": [
+          "Transactions"
+        ],
+        "operationId": "ExecuteTransaction",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "balance_changes",
+            "description": "Request `BalanceChanges` be included in the Response.",
+            "schema": {
+              "description": "Request `BalanceChanges` be included in the Response.",
+              "default": false,
+              "type": "boolean"
+            },
+            "style": "form"
+          },
+          {
+            "in": "query",
+            "name": "events",
+            "description": "Request `TransactionEvents` be included in the Response.",
+            "schema": {
+              "description": "Request `TransactionEvents` be included in the Response.",
+              "default": false,
+              "type": "boolean"
+            },
+            "style": "form"
+          },
+          {
+            "in": "query",
+            "name": "input_objects",
+            "description": "Request input `Object`s be included in the Response.",
+            "schema": {
+              "description": "Request input `Object`s be included in the Response.",
+              "default": false,
+              "type": "boolean"
+            },
+            "style": "form"
+          },
+          {
+            "in": "query",
+            "name": "output_objects",
+            "description": "Request output `Object`s be included in the Response.",
+            "schema": {
+              "description": "Request output `Object`s be included in the Response.",
+              "default": false,
+              "type": "boolean"
+            },
+            "style": "form"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/bcs": {}
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TransactionExecutionResponse"
+                }
+              },
+              "application/bcs": {}
+            }
+          }
+        }
+      }
     },
     "/system/committee/{epoch}": {
       "get": {
@@ -860,6 +929,37 @@
           }
         ]
       },
+      "BalanceChange": {
+        "type": "object",
+        "required": [
+          "address",
+          "amount",
+          "coin_type"
+        ],
+        "properties": {
+          "address": {
+            "description": "Owner of the balance change",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/Address"
+              }
+            ]
+          },
+          "amount": {
+            "description": "The amount indicate the balance value changes.\n\nA negative amount means spending coin value and positive means receiving coin value.",
+            "type": "string",
+            "format": "i128"
+          },
+          "coin_type": {
+            "description": "Type of the Coin",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/TypeTag"
+              }
+            ]
+          }
+        }
+      },
       "Bls12381PublicKey": {
         "description": "Base64 encoded data",
         "type": "string",
@@ -1683,6 +1783,39 @@
       "EffectsAuxiliaryDataDigest": {
         "$ref": "#/components/schemas/Digest"
       },
+      "EffectsFinality": {
+        "anyOf": [
+          {
+            "type": "object",
+            "required": [
+              "signature"
+            ],
+            "properties": {
+              "signature": {
+                "description": "Validator aggregated signature",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ValidatorAggregatedSignature"
+                  }
+                ]
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "checkpoint"
+            ],
+            "properties": {
+              "checkpoint": {
+                "description": "Radix-10 encoded 64-bit unsigned integer",
+                "type": "string",
+                "format": "u64"
+              }
+            }
+          }
+        ]
+      },
       "EndOfEpochData": {
         "type": "object",
         "required": [
@@ -4283,6 +4416,43 @@
       "TransactionEventsDigest": {
         "$ref": "#/components/schemas/Digest"
       },
+      "TransactionExecutionResponse": {
+        "description": "Response type for the execute transaction endpoint",
+        "type": "object",
+        "required": [
+          "effects",
+          "finality"
+        ],
+        "properties": {
+          "balance_changes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/BalanceChange"
+            }
+          },
+          "effects": {
+            "$ref": "#/components/schemas/TransactionEffects"
+          },
+          "events": {
+            "$ref": "#/components/schemas/TransactionEvents"
+          },
+          "finality": {
+            "$ref": "#/components/schemas/EffectsFinality"
+          },
+          "input_objects": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Object"
+            }
+          },
+          "output_objects": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Object"
+            }
+          }
+        }
+      },
       "TransactionExpiration": {
         "oneOf": [
           {

crates/sui-rest-api/src/openapi.rs

@@ -523,6 +523,11 @@ impl OperationBuilder {
 
         self
     }
+
+    pub fn request_body(&mut self, request_body: RequestBody) -> &mut Self {
+        self.inner.request_body = Some(ReferenceOr::Item(request_body));
+        self
+    }
 }
 
 #[derive(Default)]

crates/sui-rest-api/src/transactions/execution.rs

@@ -5,14 +5,17 @@ use std::net::SocketAddr;
 use std::sync::Arc;
 
 use axum::extract::{Query, State};
+use schemars::JsonSchema;
 use sui_sdk2::types::framework::Coin;
 use sui_sdk2::types::{
     Address, BalanceChange, CheckpointSequenceNumber, Object, Owner, SignedTransaction,
     TransactionEffects, TransactionEvents, ValidatorAggregatedSignature,
 };
 use tap::Pipe;
 
-use crate::openapi::{ApiEndpoint, RouteHandler};
+use crate::openapi::{
+    ApiEndpoint, OperationBuilder, RequestBodyBuilder, ResponseBuilder, RouteHandler,
+};
 use crate::response::Bcs;
 use crate::{accept::AcceptFormat, response::ResponseContent};
 use crate::{RestService, Result};
@@ -50,7 +53,19 @@ impl ApiEndpoint<RestService> for ExecuteTransaction {
     ) -> openapiv3::v3_1::Operation {
         generator.subschema_for::<SignedTransaction>();
 
-        openapiv3::v3_1::Operation::default()
+        OperationBuilder::new()
+            .tag("Transactions")
+            .operation_id("ExecuteTransaction")
+            .query_parameters::<ExecuteTransactionQueryParameters>(generator)
+            .request_body(RequestBodyBuilder::new().bcs_content().build())
+            .response(
+                200,
+                ResponseBuilder::new()
+                    .json_content::<TransactionExecutionResponse>(generator)
+                    .bcs_content()
+                    .build(),
+            )
+            .build()
     }
 
     fn handler(&self) -> RouteHandler<RestService> {
@@ -160,7 +175,7 @@ async fn execute_transaction(
 }
 
 /// Query parameters for the execute transaction endpoint
-#[derive(Debug, serde::Serialize, serde::Deserialize)]
+#[derive(Debug, serde::Serialize, serde::Deserialize, JsonSchema)]
 pub struct ExecuteTransactionQueryParameters {
     // TODO once transaction finality support is more fully implemented up and down the stack, add
     // back in this parameter, which will be mutally-exclusive with the other parameters. When
@@ -181,7 +196,7 @@ pub struct ExecuteTransactionQueryParameters {
 }
 
 /// Response type for the execute transaction endpoint
-#[derive(Debug, serde::Serialize, serde::Deserialize)]
+#[derive(Debug, serde::Serialize, serde::Deserialize, JsonSchema)]
 pub struct TransactionExecutionResponse {
     effects: TransactionEffects,
 
@@ -259,16 +274,27 @@ impl<'de> serde::Deserialize<'de> for EffectsFinality {
     }
 }
 
+impl JsonSchema for EffectsFinality {
+    fn schema_name() -> String {
+        ReadableEffectsFinality::schema_name()
+    }
+
+    fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
+        ReadableEffectsFinality::json_schema(gen)
+    }
+}
+
 #[serde_with::serde_as]
-#[derive(serde::Serialize, serde::Deserialize)]
-#[serde(tag = "untagged")]
+#[derive(serde::Serialize, serde::Deserialize, JsonSchema)]
+#[serde(rename = "EffectsFinality", untagged)]
 enum ReadableEffectsFinality {
     Certified {
         /// Validator aggregated signature
         signature: ValidatorAggregatedSignature,
     },
     Checkpointed {
         #[serde_as(as = "sui_types::sui_serde::Readable<sui_types::sui_serde::BigInt<u64>, _>")]
+        #[schemars(with = "crate::_schemars::U64")]
         checkpoint: CheckpointSequenceNumber,
     },
 }