expand model to include language versions of examples

Author: miguelgrinberg

Makefile

@@ -9,6 +9,7 @@ validate-no-cache: ## Validate a given endpoint request or response without loca
 
 generate:	  ## Generate the output spec
 	@echo ">> generating the spec .."
+	@make generate-language-examples
 	@npm run generate-schema --prefix compiler -- --spec ../specification/ --output ../output/
 	@npm run start --prefix typescript-generator
 
@@ -53,7 +54,6 @@ transform-expand-generics: ## Create a new schema with all generics expanded
 	@npm run transform-expand-generics --prefix compiler
 
 transform-to-openapi: ## Generate the OpenAPI definition from the compiled schema
-	@make generate-language-examples
 	@npm run transform-to-openapi -- --schema output/schema/schema.json --flavor stack --output output/openapi/elasticsearch-openapi.json
 	@npm run transform-to-openapi -- --schema output/schema/schema.json --flavor serverless --output output/openapi/elasticsearch-serverless-openapi.json
 

compiler-rs/clients_schema/src/lib.rs

@@ -484,20 +484,28 @@ impl TypeDefinition {
 
 /// The Example type is used for both requests and responses.
 ///
-/// This type definition is taken from the OpenAPI spec
+/// This type definition is based on the OpenAPI spec
 ///     https://spec.openapis.org/oas/v3.1.0#example-object
-/// with the exception of using String as the 'value' type.
+/// with the exception of using String as the 'value' type,
+/// and some custom additions.
 ///
 /// The OpenAPI v3 spec also defines the 'Example' type, so
 /// to distinguish them, this type is called SchemaExample.
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ExampleAlternative {
+    pub language: String,
+    pub code: String,
+}
+
 #[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>,
+    pub alternatives: Option<Vec<ExampleAlternative>>,
 }
 
 /// Common attributes for all type definitions

compiler-rs/clients_schema_to_openapi/src/paths.rs

@@ -340,6 +340,14 @@ pub fn add_endpoint(
                         "source": request_line + "\n" + request_body.as_str(),
                     }));
                 }
+                if let Some(alternatives) = example.alternatives.clone() {
+                    for alternative in alternatives.iter() {
+                        code_samples.push(serde_json::json!({
+                            "lang": alternative.language,
+                            "source": alternative.code.as_str(),
+                        }));
+                    }
+                }
             }
         }
         if !code_samples.is_empty() {

compiler-rs/compiler-wasm-lib/pkg/compiler_wasm_lib.js

@@ -260,6 +260,14 @@ export class Interface extends BaseType {
   variants?: Container
 }
 
+/**
+ * An alternative of an example, coded in a given language.
+ */
+export class ExampleAlternative {
+  language: string
+  code: string
+}
+
 /**
  * The Example type is used for both requests and responses
  * This type definition is taken from the OpenAPI spec
@@ -277,6 +285,8 @@ export class Example {
   value?: string
   /** A URI that points to the literal example */
   external_value?: string
+  /** An array of alternatives for this example in other languages */
+  alternatives?: ExampleAlternative[]
 }
 
 /**