Add request details to examples (#4445)

* 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

@@ -202,7 +202,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()
     };
@@ -343,8 +343,39 @@ pub fn add_endpoint(
 
         // add the x-state extension for availability
         let mut extensions = crate::availability_as_extensions(&endpoint.availability, &tac.config.flavor);
-        let mut ext_availability = crate::availability_as_extensions(&endpoint.availability, &tac.config.flavor);
-        extensions.append(&mut ext_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 {
@@ -369,7 +400,7 @@ pub fn add_endpoint(
             deprecated: endpoint.deprecation.is_some(),
             security: None,
             servers: vec![],
-            extensions
+            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 */