fix: various OpenAPI plugin fixes (#1371)

- fix HTML comments in descriptions
- group sidebar based on group tags
- enable redirects for redoc links (`#tag...`)
- scroll sidebar after redirect
- enable redirects for sidebar categories
- fix wrongly escaped inline code block
- redirect to search page if no match found

Author: B4nan

apify-api/openapi/openapi.yaml

@@ -45,8 +45,7 @@ info:
 
     To use your token in a request, either:
 
-    - Add the token to your request's `Authorization` header as `Bearer
-    <token>`.
+    - Add the token to your request's `Authorization` header as `Bearer <token>`.
     E.g., `Authorization: Bearer xxxxxxx`.
     [More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).
     (Recommended).

apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml

@@ -5,29 +5,22 @@ post:
   description: |
     Runs a specific Actor and returns its output.
 
-
     The POST payload including its `Content-Type` header is passed as `INPUT` to
     the Actor (usually <code>application/json</code>).
-
     The HTTP response contains Actors `OUTPUT` record from its default
     key-value store.
 
-
     The Actor is started with the default options; you can override them using
     various URL query parameters.
-
     If the Actor run exceeds 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> seconds,
     the HTTP response will have status 408 (Request Timeout).
 
-
     Beware that it might be impossible to maintain an idle HTTP connection for a
     long period of time, due to client timeout or network conditions. Make sure your HTTP client is
     configured to have a long enough connection timeout.
-
     If the connection breaks, you will not receive any information about the run
     and its status.
 
-
     To run the Actor asynchronously, use the [Run
     Actor](#/reference/actors/run-collection/run-actor) API endpoint instead.
   operationId: act_runSync_post
@@ -42,9 +35,9 @@ post:
         example: janedoe~my-actor
     - name: outputRecordKey
       in: query
-      description: |-
+      description: |
         Key of the record from run's default key-value store to be returned
-                                                     in the response. By default, it is `OUTPUT`.
+        in the response. By default, it is `OUTPUT`.
       style: form
       explode: true
       schema:
@@ -103,12 +96,9 @@ post:
       description: |
         Specifies optional webhooks associated with the Actor run, which can be
         used to receive a notification
-
         e.g. when the Actor finished or failed. The value is a Base64-encoded
         JSON array of objects defining the webhooks. For more information, see
-
-        [Webhooks
-        documentation](https://docs.apify.com/platform/integrations/webhooks).
+        [Webhooks documentation](https://docs.apify.com/platform/integrations/webhooks).
       style: form
       explode: true
       schema:
@@ -143,9 +133,8 @@ post:
           example:
             error:
               type: run-failed
-              message: >-
-                Actor run did not succeed (run ID: 55uatRrZib4xbZs, status:
-                FAILED)
+              message: |
+                Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)
     '408':
       description: ''
       headers: {}
@@ -168,23 +157,17 @@ get:
   summary: Without input
   description: |
     Runs a specific Actor and returns its output.
-
     The run must finish in 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> seconds
     otherwise the API endpoint returns a timeout error.
-
     The Actor is not passed any input.
 
-
     Beware that it might be impossible to maintain an idle HTTP connection for a
     long period of time,
-
     due to client timeout or network conditions. Make sure your HTTP client is
     configured to have a long enough connection timeout.
-
     If the connection breaks, you will not receive any information about the run
     and its status.
 
-
     To run the Actor asynchronously, use the [Run
     Actor](#/reference/actors/run-collection/run-actor) API endpoint instead.
   operationId: act_runSync_get
@@ -199,9 +182,9 @@ get:
         example: janedoe~my-actor
     - name: outputRecordKey
       in: query
-      description: |-
+      description: |
         Key of the record from run's default key-value store to be returned
-                                                     in the response. By default, it is `OUTPUT`.
+        in the response. By default, it is `OUTPUT`.
       style: form
       explode: true
       schema:
@@ -260,12 +243,9 @@ get:
       description: |
         Specifies optional webhooks associated with the Actor run, which can be
         used to receive a notification
-
         e.g. when the Actor finished or failed. The value is a Base64-encoded
         JSON array of objects defining the webhooks. For more information, see
-
-        [Webhooks
-        documentation](https://docs.apify.com/platform/integrations/webhooks).
+        [Webhooks documentation](https://docs.apify.com/platform/integrations/webhooks).
       style: form
       explode: true
       schema:

apify-docs-theme/src/theme/NotFound.jsx

@@ -1,6 +1,6 @@
-import React from 'react';
 import { PageMetadata } from '@docusaurus/theme-common';
 import Layout from '@theme/Layout';
+import React from 'react';
 
 export default function NotFound() {
     return (

apify-docs-theme/src/theme/SearchPage/index.js

@@ -17,6 +17,7 @@ import {
 } from '@docusaurus/theme-common/internal';
 import Translate, { translate } from '@docusaurus/Translate';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import { useLocation } from '@docusaurus/router';
 import {
     useAlgoliaThemeConfig,
     useSearchResultUrlProcessor,
@@ -120,6 +121,8 @@ function SearchPageContent() {
     const documentsFoundPlural = useDocumentsFoundPlural();
     const docsSearchVersionsHelpers = useDocsSearchVersionsHelpers();
     const [searchQuery, setSearchQuery] = useSearchQueryString();
+    const location = useLocation();
+    const notFound = new URLSearchParams(location.search).get('not-found');
     const initialSearchResultState = {
         items: [],
         query: null,
@@ -302,7 +305,14 @@ function SearchPageContent() {
             </Head>
 
             <div className="container margin-vert--lg">
-                <h1>{getTitle()}</h1>
+                {notFound ? (
+                    <>
+                        <h1>Page Not Found</h1>
+                        <h2>{getTitle()}</h2>
+                    </>
+                ) : (
+                    <h1>{getTitle()}</h1>
+                )}
 
                 <form className="row" onSubmit={(e) => e.preventDefault()}>
                     <div

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

@@ -990,14 +990,19 @@ html[data-theme='dark'] .actionLink:hover::after {
     }
 }
 
-aside li.section-header > div > .menu__link {
+aside li.section-header > div > .menu__link,
+aside li.section-header > ul > li > div > .menu__link {
     text-transform: uppercase;
     opacity: 0.8;
     font-size: 16px;
     font-weight: 700;
     margin: 0;
 }
 
+aside li.section-header > div > .menu__link {
+    font-size: 20px;
+}
+
 aside li.section-header.menu__list-item {
     margin-top: 15px;
     margin-bottom: 5px;
@@ -1011,6 +1016,11 @@ aside li.section-header > .menu__list {
     padding-left: 0;
 }
 
+.theme-doc-sidebar-menu li.section-header > ul > li .menu__list-item-collapsible:hover,
+.theme-doc-sidebar-menu li.section-header > ul > li .menu__list-item-collapsible--active {
+    background: inherit !important;
+}
+
 .beta-chip {
     display: inline-block;
     border: 1px solid #ccc;

apify-docs-theme/static/js/custom.js

@@ -63,7 +63,7 @@ function scrollSidebarItemIntoView() {
 
 // handles automatic scrolling of the API reference sidebar (openapi-docs)
 function scrollOpenApiSidebarItemIntoView() {
-    const $li = document.querySelector(`li > a.menu__link--active[href]`);
+    const $li = document.querySelector(`ul.theme-doc-sidebar-menu a.menu__link--active[href]`);
 
     if (!$li) {
         return;
@@ -76,27 +76,31 @@ function scrollOpenApiSidebarItemIntoView() {
 }
 
 function redirectOpenApiDocs() {
-    const { hash, pathname } = new URL(window.location.href);
+    const { hash, pathname, origin } = new URL(window.location.href);
 
     // TODO change to '/api/v2'
     if (pathname.replace(/\/$/, '') !== '/api/v2-new') {
         return;
     }
 
-    if (hash.startsWith('#/reference/')) {
-        const sidebarItems = document.querySelectorAll('[data-altids]');
+    const sidebarItems = document.querySelectorAll('[data-altids]');
+
+    if (hash.startsWith('#/reference/') || hash.startsWith('#tag/')) {
+        let matched = false;
 
         for (const item of sidebarItems) {
             const ids = item.getAttribute('data-altids').split(',');
+
             if (ids.find((variant) => variant === hash)) {
+                matched = true;
                 item.click();
+                setTimeout(() => scrollOpenApiSidebarItemIntoView(), 200);
             }
         }
-    }
 
-    if (hash.startsWith('#tag/')) {
-        const id = hash.substring('#tag/'.length);
-        console.log('redirect', { id, hash });
+        if (!matched) {
+            window.location.href = `${origin}/search?q=${hash.slice(1)}&not-found=1`;
+        }
     }
 }
 
@@ -121,7 +125,7 @@ window.addEventListener('load', () => {
     setTimeout(() => scrollSidebarItemIntoView(), 1000);
 
     // docusaurus-openapi-docs plugin: scroll sidebar into viewport, no need for a large timeout here
-    setTimeout(() => scrollOpenApiSidebarItemIntoView(), 100);
+    setTimeout(() => scrollOpenApiSidebarItemIntoView(), 200);
 });
 
 window.addEventListener('popstate', () => {

docusaurus.config.js

@@ -1,6 +1,7 @@
 const { join } = require('node:path');
 
 const clsx = require('clsx');
+const { createApiPageMD } = require('docusaurus-plugin-openapi-docs/lib/markdown');
 
 const { config } = require('./apify-docs-theme');
 const { collectSlugs } = require('./tools/utils/collectSlugs');
@@ -195,15 +196,28 @@ module.exports = {
                     v2: {
                         specPath: 'apify-api.yaml',
                         outputDir: './sources/api',
+                        markdownGenerators: {
+                            createApiPageMD: (pageData) => {
+                                let md = createApiPageMD(pageData);
+
+                                // HTML comments are wrongly escaped, we need to undo that
+                                if (md.includes('<!--')) {
+                                    md = md.replace('&lt;!--', '<!--');
+                                    md = md.replace('--&gt;', '-->');
+                                }
+
+                                return md;
+                            },
+                        },
                         sidebarOptions: {
-                            groupPathsBy: 'tag',
+                            groupPathsBy: 'tagGroup',
                             categoryLinkSource: 'tag',
                             sidebarCollapsed: false,
                             sidebarCollapsible: false,
                             sidebarGenerators: {
                                 createDocItem: (item, context) => {
                                     const legacyUrls = item.api?.['x-legacy-doc-urls'] ?? [];
-                                    const altIds = legacyUrls.map((url) => {
+                                    const altids = legacyUrls.map((url) => {
                                         const { hash } = new URL(url);
                                         return hash;
                                     });
@@ -223,7 +237,7 @@ module.exports = {
                                         type: 'doc',
                                         id: context.basePath === '' ? `${id}` : `${context.basePath}/${id}`,
                                         label: sidebarLabel ?? title ?? id,
-                                        customProps: { altIds },
+                                        customProps: { altids },
                                         className,
                                     };
                                 },

patches/docusaurus-plugin-openapi-docs+0.0.0-961.patch

@@ -0,0 +1,36 @@
+diff --git a/node_modules/docusaurus-plugin-openapi-docs/lib/sidebars/index.js b/node_modules/docusaurus-plugin-openapi-docs/lib/sidebars/index.js
+index 5802904..576c3ed 100644
+--- a/node_modules/docusaurus-plugin-openapi-docs/lib/sidebars/index.js
++++ b/node_modules/docusaurus-plugin-openapi-docs/lib/sidebars/index.js
+@@ -139,9 +139,16 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
+         }
+         const taggedApiItems = apiItems.filter((item) => { var _a; return !!((_a = item.api.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
+         const taggedSchemaItems = schemaItems.filter((item) => { var _a; return !!((_a = item.schema["x-tags"]) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
++        const altids = [];
++
++        if (tagObject?.['x-legacy-doc-urls']) {
++            altids.push(...tagObject['x-legacy-doc-urls']);
++        }
++
+         return {
+             type: "category",
+             label: (_a = tagObject === null || tagObject === void 0 ? void 0 : tagObject["x-displayName"]) !== null && _a !== void 0 ? _a : tag,
++            customProps: { altids },
+             link: linkConfig,
+             collapsible: sidebarCollapsible,
+             collapsed: sidebarCollapsed,
+@@ -201,11 +208,12 @@ function generateSidebarSlice(sidebarOptions, options, api, tags, docPath, tagGr
+                     filteredTags.push(tag);
+                 }
+             });
++            const { sidebarCollapsed, sidebarCollapsible } = sidebarOptions;
+             const groupCategory = {
+                 type: "category",
+                 label: tagGroup.name,
+-                collapsible: true,
+-                collapsed: true,
++                collapsible: sidebarCollapsible,
++                collapsed: sidebarCollapsed,
+                 items: groupByTags(api, sidebarOptions, options, [filteredTags], docPath),
+             };
+             if (options.showSchemas) {

sources/api/sidebars.js

@@ -1,12 +1,22 @@
+// eslint-disable-next-line global-require
+const items = require('./sidebar.ts');
+
+for (const item of items) {
+    // this is wrongly rendered in each category (openapi group tag)
+    if (item.items[0].id === 'apify-api') {
+        item.items.shift();
+    }
+}
+
 module.exports = {
     api: [
         {
             type: 'category',
             label: 'Apify API',
             collapsible: false,
             className: 'section-header',
-            // eslint-disable-next-line global-require
-            items: require('./sidebar.ts'),
+            link: { type: 'doc', id: 'apify-api' },
+            items,
         },
     ],
 };