add language client examples to YAML files (#4514) (#4565)

* expand model to include language versions of examples

* add language client examples to YAML files

* use $ELASTICSEARCH_URL in curl examples

* remove unnecessary generate-language-examples task from the openapi generation

* upgrade request converter to latest

Author: miguelgrinberg

Makefile

@@ -8,6 +8,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
 
@@ -40,6 +41,7 @@ setup:	## Install dependencies for contrib target
 	@npm install --prefix compiler
 	@npm install --prefix typescript-generator
 	@npm install @redocly/cli
+	@npm install --prefix docs/examples
 
 clean-dep:	## Clean npm dependencies
 	@rm -rf compiler/node_modules
@@ -67,6 +69,10 @@ overlay-docs: ## Apply overlays to OpenAPI documents
 	@npx @redocly/cli bundle output/openapi/elasticsearch-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-openapi.examples.json
 	rm output/openapi/elasticsearch-openapi.tmp*.json
 
+generate-language-examples:
+	@node docs/examples/generate-language-examples.js
+	@npm run format:fix-examples --prefix compiler
+
 lint-docs: ## Lint the OpenAPI documents after overlays
 	@npx @redocly/cli lint "output/openapi/elasticsearch-*.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 

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

@@ -355,6 +355,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_bg.wasm

@@ -8,6 +8,7 @@
     "lint:fix": "ts-standard --fix src",
     "format:check": "prettier --config .prettierrc.json --loglevel warn --check ../specification/",
     "format:fix": "prettier --config .prettierrc.json --loglevel warn --write ../specification/",
+    "format:fix-examples": "prettier --config .prettierrc.json --loglevel warn --write ../specification/**/*.yaml",
     "generate-schema": "ts-node src/index.ts",
     "transform-expand-generics": "ts-node src/transform/expand-generics.ts",
     "transform-to-openapi": "ts-node src/transform/schema-to-openapi.ts",

compiler/package.json

@@ -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[]
 }
 
 /**

compiler/src/model/metamodel.ts

@@ -0,0 +1,80 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseDocument: yamlParseDocument } = require('yaml');
+const { convertRequests, loadSchema } = require('@elastic/request-converter');
+
+const LANGUAGES = ['Python', 'JavaScript', 'Ruby', 'PHP', 'curl'];
+
+async function generateLanguages(example) {
+  const doc = yamlParseDocument(await fs.promises.readFile(example, 'utf8'));
+  const data = doc.toJS();
+  let request = data.method_request;
+  if (data.value) {
+    if (typeof data.value === 'string') {
+      request += '\n' + data.value;
+    }
+    else {
+      request += '\n' + JSON.stringify(data.value);
+    }
+  }
+  data.alternatives = [];
+  for (const lang of LANGUAGES) {
+    data.alternatives.push({
+      language: lang,
+      code: (await convertRequests(request, lang, {})).trim(),
+    });
+  }
+  doc.delete('alternatives');
+  doc.add(doc.createPair('alternatives', data.alternatives));
+  await fs.promises.writeFile(example, doc.toString({lineWidth: 132}));
+}
+
+async function* walkExamples(dir) {
+  for await (const d of await fs.promises.opendir(dir)) {
+    const entry = path.join(dir, d.name);
+    if (d.isDirectory()) {
+      yield* walkExamples(entry);
+    }
+    else if (d.isFile() && entry.includes('/examples/request/') && entry.endsWith('.yaml')) {
+      yield entry;
+    }
+  }
+}
+
+async function main() {
+  let count = 0;
+  let errors = 0;
+  await loadSchema('output/schema/schema.json');
+  for await (const example of walkExamples('./specification/')) {
+    try {
+      await generateLanguages(example);
+    }
+    catch (err) {
+      console.log(`${example}: ${err}`);
+      errors += 1;
+    }
+    count += 1;
+  }
+  console.log(`${count} examples processed, ${errors} errors.`);
+}
+
+main();