feat: add code samples for actor collection

.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/javascript/acts_get.js

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

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

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

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,
+    },
+});

apify-docs-theme/src/theme/custom.css

@@ -162,7 +162,7 @@ html[data-theme='dark'] {
     --ifm-footer-link-color: #6b6e80;
     --max-layout-width: 1440px;
 
-    --ifm-code-background: #f6f8fa;
+    --ifm-code-background: var(--ifm-pre-background);
 
     --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);