Feat: auto-generate x-codesamples

Author: m-murasovs

.redocly.yaml

@@ -27,3 +27,4 @@ plugins:
 decorators:
     apify/legacy-doc-url-decorator: on
     apify/client-references-links-decorator: on
+    apify/code-samples-decorator: on

apify-api/openapi/code_samples/js/acts_get.js renamed to apify-api/openapi/code_samples/javascript/acts_get.js

@@ -1,8 +1,6 @@
 import { ApifyClient } from 'apify-client';
 
 const apifyClient = new ApifyClient({ token: 'my-token' });
-const actorCollectionClient = apifyClient.actors();
-
-const { items } = await actorCollectionClient.list();
+const { items } = await apifyClient.actors().list();
 
 console.log(items);

apify-api/openapi/code_samples/js/acts_post.js renamed to apify-api/openapi/code_samples/javascript/acts_post.js

@@ -1,8 +1,6 @@
 import { ApifyClient } from 'apify-client';
 
 const apifyClient = new ApifyClient({ token: 'my-token' });
-const actorCollectionClient = apifyClient.actors();
-
-const myActor = await actorCollectionClient.create({ name: 'my-actor' });
+const myActor = await apifyClient.actors().create({ name: 'my-actor' });
 
 console.log(myActor);

apify-api/openapi/paths/actors/acts.yaml

@@ -94,11 +94,6 @@ get:
   x-py-parent: ActorCollectionClientAsync
   x-py-name: list
   x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/ActorCollectionClientAsync#list
-  x-codeSamples:
-    - lang: JavaScript
-      label: JS client
-      source:
-        $ref: ../../code_samples/js/acts_get.js
 
 post:
   tags:
@@ -245,8 +240,3 @@ post:
   x-py-parent: ActorCollectionClientAsync
   x-py-name: create
   x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/ActorCollectionClientAsync#create
-  x-codeSamples:
-    - lang: JavaScript
-      label: JS client
-      source:
-        $ref: ../../code_samples/js/acts_post.js

apify-api/plugins/apify.js

@@ -1,4 +1,5 @@
 const ClientReferencesLinksDecorator = require('./decorators/client-references-links-decorator');
+const CodeSamplesDecorator = require('./decorators/code-samples-decorator');
 const LegacyDocUrlDecorator = require('./decorators/legacy-doc-url-decorator');
 
 module.exports = {
@@ -7,6 +8,7 @@ module.exports = {
         oas3: {
             'legacy-doc-url-decorator': LegacyDocUrlDecorator,
             'client-references-links-decorator': ClientReferencesLinksDecorator,
+            'code-samples-decorator': CodeSamplesDecorator,
         },
     },
 };

apify-api/plugins/decorators/code-samples-decorator.js

@@ -0,0 +1,59 @@
+const { existsSync } = require('fs');
+const path = require('path');
+
+const X_CODE_SAMPLES_PROPERTY = 'x-codeSamples';
+
+const LANGUAGES = [
+    { lang: 'JavaScript', label: 'JS client' },
+];
+
+/**
+ * This decorator adds the x-codeSamples property to the schema object if a file with the operationId exists in the
+ * code samples directory.
+ * This helps us add the samples in a consistent way and find out which operations are missing a sample.
+ *
+ * The added sample link will look like this:
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS client
+ *     source:
+ *        $ref: ../../code_samples/js/acts_post.js
+ */
+function CodeSamplesDecorator(target) {
+    if (!target.operationId) return;
+
+    const codeSamples = [];
+
+    for (const { lang, label } of LANGUAGES) {
+        const codeSamplePath = path.join(__dirname, `../../openapi/code_samples/${lang.toLowerCase()}/${target.operationId}.js`);
+
+        if (!existsSync(codeSamplePath)) {
+            // Just use this console log in development to see which operations are missing a code sample.
+            // console.log(`Missing code sample for operation ${target.operationId}`);
+            return;
+        }
+
+        codeSamples.push({
+            lang,
+            label,
+            source: {
+                $ref: codeSamplePath,
+            },
+        });
+    }
+
+    if (codeSamples.length) {
+        target[X_CODE_SAMPLES_PROPERTY] = codeSamples;
+    }
+}
+
+module.exports = () => ({
+    // Redocly is using a visitor pattern. What the following code does is that whenever the traverser leaves a node of
+    // type Tag or Operation, it executes CodeSamplesDecorator on it.
+    Tag: {
+        leave: CodeSamplesDecorator,
+    },
+    Operation: {
+        leave: CodeSamplesDecorator,
+    },
+});