Add request details to examples (#4445) (#4486)

* add request heading line to request examples

* add request heading line to response examples

* changes to the compiler to include the request heading

Author: miguelgrinberg

compiler-rs/clients_schema/src/lib.rs

@@ -494,6 +494,7 @@ impl TypeDefinition {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SchemaExample {
     pub summary: Option<String>,
+    pub method_request: Option<String>,
     pub description: Option<String>,
     pub value: Option<String>,
     pub external_value: Option<String>,

compiler-rs/clients_schema_to_openapi/src/paths.rs

@@ -198,7 +198,7 @@ pub fn add_endpoint(
     // If this endpoint response has examples in schema.json, convert them to the
     // OpenAPI format and add them to the endpoint response in the OpenAPI document.
     let response_examples = if let Some(examples) = &response_def.examples {
-         get_openapi_examples(examples)
+        get_openapi_examples(examples)
     } else {
         IndexMap::new()
     };
@@ -251,6 +251,42 @@ pub fn add_endpoint(
 
         let sum_desc = split_summary_desc(&endpoint.description);
 
+        // add the x-state extension for availability
+        let mut extensions = crate::availability_as_extensions(&endpoint.availability);
+
+        // add the x-codeSamples extension
+        let mut code_samples = vec![];
+        if let Some(examples) = request.examples.clone() {
+            if let Some((_, example)) = examples.first() {
+                let request_line = example.method_request.clone().unwrap_or(String::from(""));
+                let request_body = example.value.clone().unwrap_or(String::from(""));
+                if !request_line.is_empty() {
+                    code_samples.push(serde_json::json!({
+                        "lang": "Console",
+                        "source": request_line + "\n" + request_body.as_str(),
+                    }));
+                }
+            }
+        }
+        if code_samples.is_empty() {
+            // if there are no example requests we look for example responses
+            // this can only happen for examples that do not have a request body
+            if let Some(examples) = response_def.examples.clone() {
+                if let Some((_, example)) = examples.first() {
+                    let request_line = example.method_request.clone().unwrap_or(String::from(""));
+                    if !request_line.is_empty() {
+                        code_samples.push(serde_json::json!({
+                            "lang": "Console",
+                            "source": request_line + "\n",
+                        }));
+                    }
+                }
+            }
+        }
+        if !code_samples.is_empty() {
+            extensions.insert("x-codeSamples".to_string(), serde_json::json!(code_samples));
+        }
+
         // Create the operation, it will be repeated if we have several methods
         let operation = openapiv3::Operation {
             tags: if let Some(doc_tag) = &endpoint.doc_tag {
@@ -274,7 +310,7 @@ pub fn add_endpoint(
             deprecated: endpoint.deprecation.is_some(),
             security: None,
             servers: vec![],
-            extensions: crate::availability_as_extensions(&endpoint.availability),
+            extensions,
         };
 
 

compiler-rs/compiler-wasm-lib/pkg/compiler_wasm_lib_bg.wasm

@@ -271,6 +271,8 @@ export class Example {
   summary?: string
   /** Long description. */
   description?: string
+  /** request method and URL */
+  method_request?: string
   /** Embedded literal example. Mutually exclusive with `external_value` */
   value?: string
   /** A URI that points to the literal example */