feat: add code samples for actor collection (#1318)

Here are the first two code samples for the API docs. These are for the
JS client and are a tentative proposal. When we've agreed on how they
should look, I'll also add the ones for the Python client.

**Note**: The Palo Alto plugin currently doesn't support TypeScript and
there's no straightforward way to add multiple custom code samples for
the same language (I thought we could have JS and TS client samples
under the JavaScript bit).
I have created an issue asking about this on the plugin's repo:
PaloAltoNetworks/docusaurus-openapi-docs#1035

**Note 2**: For the POST request, as mentioned by @netmilk , it would be
nice to have the request body present, but that would be complicated,
since the schema isn't available in the examples, and would make the
testing harder. I think it's not so bad, though, since the request body
is shown right under the code example, so it's quite easy to find.

So, on the new docs it will look like this:
![CleanShot 2024-12-04 at 16 06
42@2x](https://github.com/user-attachments/assets/d4c00c7b-d5e3-476c-bb3c-61fa9e1ea0e3)

And in the old/current docs like this: (I had to fix the background
color)
![CleanShot 2024-12-04 at 16 27
02@2x](https://github.com/user-attachments/assets/25279a78-8738-433d-bf31-54aee9205d69)

Author: janbuchar

.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);