add language client examples to YAML files

Author: miguelgrinberg

Makefile

@@ -43,6 +43,7 @@ setup:	## Install dependencies for contrib target
 	@npm install --prefix validator
 	@npm install --prefix specification
 	@npm install @redocly/cli
+	@npm install --prefix docs/examples
 
 clean-dep:	## Clean npm dependencies
 	@rm -rf compiler/node_modules
@@ -52,6 +53,7 @@ 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
 
@@ -74,6 +76,10 @@ overlay-docs: ## Apply overlays to OpenAPI documents
 	rm output/openapi/elasticsearch-serverless-openapi.tmp*.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/package.json

@@ -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",

docs/examples/generate-language-examples.js

@@ -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();