diff --git a/.redocly.yaml b/.redocly.yaml index 2c77b6088a..f28992c32d 100644 --- a/.redocly.yaml +++ b/.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 diff --git a/apify-api/openapi/code_samples/javascript/acts_get.js b/apify-api/openapi/code_samples/javascript/acts_get.js new file mode 100644 index 0000000000..ef13872c19 --- /dev/null +++ b/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); diff --git a/apify-api/openapi/code_samples/javascript/acts_post.js b/apify-api/openapi/code_samples/javascript/acts_post.js new file mode 100644 index 0000000000..a2fd96905d --- /dev/null +++ b/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); diff --git a/apify-api/plugins/apify.js b/apify-api/plugins/apify.js index 0799d271c7..a739c215d9 100644 --- a/apify-api/plugins/apify.js +++ b/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, }, }, }; diff --git a/apify-api/plugins/decorators/code-samples-decorator.js b/apify-api/plugins/decorators/code-samples-decorator.js new file mode 100644 index 0000000000..a951460980 --- /dev/null +++ b/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, + }, +}); diff --git a/apify-docs-theme/src/theme/custom.css b/apify-docs-theme/src/theme/custom.css index 16554a2eba..1407461c87 100644 --- a/apify-docs-theme/src/theme/custom.css +++ b/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);