Add examples for delay, ErrorResponse and SendResponse (#2283)

restatedev · Nov 13, 2024 · 0f579f6 · 0f579f6
1 parent 3848fa9
commit 0f579f6
Show file tree

Hide file tree

Showing 3 changed files with 79 additions and 39 deletions.
diff --git a/crates/ingress-http/src/handler/error.rs b/crates/ingress-http/src/handler/error.rs
@@ -86,6 +86,7 @@ pub(crate) enum HandlerError {
     DispatcherError(#[from] RequestDispatcherError),
 }
 
+// IMPORTANT! If you touch this, please update crates/types/src/schema/openapi.rs too
 #[derive(Debug, Serialize)]
 #[serde(untagged)]
 pub enum ErrorResponse {

diff --git a/crates/ingress-http/src/handler/service_handler.rs b/crates/ingress-http/src/handler/service_handler.rs
@@ -47,6 +47,7 @@ pub(crate) enum SendStatus {
     PreviouslyAccepted,
 }
 
+// IMPORTANT! If you touch this, please update crates/types/src/schema/openapi.rs too
 #[derive(Debug, Serialize)]
 #[cfg_attr(test, derive(serde::Deserialize))]
 #[serde(rename_all = "camelCase")]

diff --git a/crates/types/src/schema/openapi.rs b/crates/types/src/schema/openapi.rs
@@ -256,6 +256,7 @@ fn delay_parameter() -> Parameter {
         .schema(Some(
             string_json_schema()
         ))
+        .example(Some(serde_json::Value::String("10s".to_string())))
         .required(Required::False)
         .description(Some("Specify the delay to execute the operation, for more info check the [delay documentation](https://docs.restate.dev/invoke/http#sending-a-delayed-message-over-http)"))
         .build()
@@ -295,59 +296,96 @@ const ERROR_RESPONSE_REF_NAME: &str = "Error";
 fn error_response() -> Response {
     Response::builder()
         .description("Error response")
-        .content("application/json", Content::new(Some(Schema::new(json!({
-            "type": "object",
-            "title": "Error",
-            "description": "Generic error used by Restate to propagate Terminal errors/exceptions back to callers",
-            "properties": {
-                "code": {
-                    "type": "number",
-                    "title": "error code"
-                },
-                "message": {
-                    "type": "string",
-                    "title": "Error message"
-                },
-                "description": {
-                    "type": "string",
-                    "title": "Verbose error description"
-                }
-            },
-            "required": ["message"],
-            "additionalProperties": false
-        })))))
+        .content(
+            "application/json",
+            ContentBuilder::new()
+                .schema(Some(Schema::new(error_response_json_schema())))
+                .example(Some(error_response_example()))
+                .build(),
+        )
         .build()
 }
 
+// Ideally we code generate this
+fn error_response_json_schema() -> serde_json::Value {
+    json!({
+        "type": "object",
+        "title": "Error",
+        "description": "Generic error used by Restate to propagate Terminal errors/exceptions back to callers",
+        "properties": {
+            "code": {
+                "type": "number",
+                "title": "error code"
+            },
+            "message": {
+                "type": "string",
+                "title": "Error message"
+            },
+            "description": {
+                "type": "string",
+                "title": "Verbose error description"
+            }
+        },
+        "required": ["message"],
+        "additionalProperties": false
+    })
+}
+
+// Ideally we code generate this
+fn error_response_example() -> serde_json::Value {
+    json!({
+        "code": 500,
+        "message": "Internal server error",
+        "description": "Very bad error happened"
+    })
+}
+
 const SEND_RESPONSE_REF_NAME: &str = "Send";
 
 fn send_response() -> Response {
     Response::builder()
         .description("Send response")
         .content(
             "application/json",
-            Content::new(Some(Schema::new(json!({
-                "type": "object",
-                "properties": {
-                    "invocationId": {
-                        "type": "string"
-                    },
-                    "status": {
-                        "type": "string",
-                        "enum": ["Accepted", "PreviouslyAccepted"]
-                    },
-                    "executionTime": {
-                        "type": "string",
-                        "format": "date-time"
-                    }
-                },
-                "required": ["invocationId", "status"],
-                "additionalProperties": false
-            })))),
+            ContentBuilder::new()
+                .schema(Some(Schema::new(send_response_json_schema())))
+                .example(Some(send_response_example()))
+                .build(),
         )
         .build()
 }
 
+// Ideally we code generate this
+fn send_response_json_schema() -> serde_json::Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "invocationId": {
+                "type": "string"
+            },
+            "status": {
+                "type": "string",
+                "enum": ["Accepted", "PreviouslyAccepted"]
+            },
+            "executionTime": {
+                "type": "string",
+                "format": "date-time",
+                "description": "Time when the invocation will be executed, in case 'delay' is used"
+            }
+        },
+        "required": ["invocationId", "status"],
+        "additionalProperties": false
+    })
+}
+
+// Ideally we code generate this
+fn send_response_example() -> serde_json::Value {
+    json!({
+        "invocationId": "inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz",
+        "status": "Accepted",
+    })
+}
+
 fn string_json_schema() -> Schema {
     Schema::new(json!({"type": "string"}))
 }