feat: better openapi docs (#1300)

This PR overhauls our OpenAPI setup completely:
- new API docs are available on
https://docs.apify.com/api/v2-new/apify-api
- use https://github.com/PaloAltoNetworks/docusaurus-openapi-docs
instead of the redoc plugin
- embed the OpenAPI specs to this repository (`apify-api` folder)
	- both the specs yaml file and the MDX files are git ignored
- the spec include (not only) corrections from
apify/openapi#108
- provide NPM scripts to work with the OpenAPI specs, namely
- `npm start` will generate the specs as well as produce the MDX files
out of them
- `npm run api:rebuild` will rebuild the yaml spec file and recreate the
MDX files
- update docusaurus to v3.6.3 and enable `faster` mode (rust based
tooling)
- cache Run on Apify code hashes locally

Things to discuss:
- ~index page now only redirects, maybe we should move the content from
the introduction section (so outside of OpenAPI specs)~
- ~folder structure~
- OpenAPI tests and schemathesis
- nested readmes in openapi folder

---------

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Jindřich Bär <[email protected]>

Author: 3 people

.github/workflows/apiary.yaml

@@ -18,20 +18,23 @@ jobs:
 
         steps:
             -   uses: actions/checkout@v4
-            -   name: Use Node.js 20
+            -   name: Use Node.js 22
                 uses: actions/setup-node@v4
                 with:
-                    node-version: 20
+                    node-version: 22
                     cache: 'npm'
                     cache-dependency-path: 'package-lock.json'
                     always-auth: 'true'
                     registry-url: 'https://npm.pkg.github.com/'
                     scope: '@apify-packages'
 
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
             -   name: Build docs
                 run: |
                     npm ci --force
-                    npm update @apify/openapi
                     npm run build
                 env:
                     APIFY_SIGNING_TOKEN: ${{ secrets.APIFY_SIGNING_TOKEN }}

.github/workflows/docs.yaml

@@ -11,20 +11,23 @@ jobs:
         steps:
             -   uses: actions/checkout@v4
 
-            -   name: Use Node.js 20
+            -   name: Use Node.js 22
                 uses: actions/setup-node@v4
                 with:
-                    node-version: 20
+                    node-version: 22
                     cache: 'npm'
                     cache-dependency-path: 'package-lock.json'
                     always-auth: 'true'
                     registry-url: 'https://npm.pkg.github.com/'
                     scope: '@apify-packages'
 
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
             -   name: Build docs
                 run: |
                     npm ci --force
-                    npm update @apify/openapi
                     npm run build
                 env:
                     APIFY_SIGNING_TOKEN: ${{ secrets.APIFY_SIGNING_TOKEN }}

.github/workflows/lychee.yml

@@ -0,0 +1,43 @@
+name: Check OpenAPI specs
+
+on:
+    push:
+
+#env:
+#    APIFY_STAGING_TOKEN: ${{ secrets.APIFY_STAGING_TOKEN }}
+
+jobs:
+    build:
+        name: Build the specification file
+        runs-on: ubuntu-latest
+
+        steps:
+            -   uses: actions/checkout@v4
+
+            -   name: Use Node.js 22
+                uses: actions/setup-node@v4
+                with:
+                    node-version: 22
+                    cache: 'npm'
+                    cache-dependency-path: 'package-lock.json'
+                    registry-url: 'https://npm.pkg.github.com/'
+                    scope: '@apify-packages'
+
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
+            -   name: Install Dependencies
+                run: npm ci --force
+                env:
+                    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+            -   run: |
+                    npm ci
+                    npm run redoc:test
+
+# TODO
+#            -   uses: actions/setup-python@v5
+#                with:
+#                    python-version: '3.10'
+#            -   run: python -m pip install schemathesis==3.35.0

.github/workflows/openapi.yaml

@@ -8,27 +8,33 @@ on:
 
 jobs:
     look_for_change:
-      if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
-      runs-on: ubuntu-latest
-      outputs:
-          theme_changed: ${{ steps.changed-theme-files.outputs.any_changed }}
-      steps:
-          -   uses: actions/checkout@v4
-              with:
-                  fetch-depth: 0
-
-          -   name: Use Node.js 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: 20
-
-          -   name: Check changes in theme
-              id: changed-theme-files
-              uses: tj-actions/changed-files@v45
-              with:
-                since_last_remote_commit: "true"
-                files: |
-                    apify-docs-theme/**
+        if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
+        runs-on: ubuntu-latest
+        outputs:
+            theme_changed: ${{ steps.changed-theme-files.outputs.any_changed }}
+        steps:
+            -   uses: actions/checkout@v4
+                with:
+                    fetch-depth: 0
+
+            -   name: Use Node.js 22
+                uses: actions/setup-node@v4
+                with:
+                    node-version: 22
+                    cache: 'npm'
+                    cache-dependency-path: 'package-lock.json'
+
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
+            -   name: Check changes in theme
+                id: changed-theme-files
+                uses: tj-actions/changed-files@v45
+                with:
+                    since_last_remote_commit: "true"
+                    files: |
+                        apify-docs-theme/**
 
     publish:
         needs: look_for_change
@@ -39,14 +45,18 @@ jobs:
                 with:
                     token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
 
-            -   name: Use Node.js 20
+            -   name: Use Node.js 22
                 uses: actions/setup-node@v4
                 with:
-                    node-version: 20
+                    node-version: 22
                     cache: 'npm'
                     cache-dependency-path: 'package-lock.json'
                     always-auth: 'true'
 
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
             -   name: Setup git user and npm
                 run: |
                     git config --global user.name "Apify Release Bot"
@@ -70,33 +80,33 @@ jobs:
                     GIT_USER: "barjin:${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}"
                     GH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
 
-            - name: Wait until the new theme version is available on npm
-              run: |
-                cd $GITHUB_WORKSPACE/apify-docs-theme
-                PACKAGE_JSON=$(cat package.json);
-                PACKAGE_NAME=$(jq -r .name <(echo $PACKAGE_JSON));
-                PACKAGE_VER=$(jq -r .version <(echo $PACKAGE_JSON));
-                for i in $(seq 1 10); do
-                    EXIT_CODE=0;
-                    npm show $PACKAGE_NAME@$PACKAGE_VER || EXIT_CODE=1;
-                    if [[ $EXIT_CODE -eq 1 ]]; then
-                        echo "The new package version ($PACKAGE_VER) is not yet available, waiting 30 seconds...";
-                        sleep 30;
-                        continue;
-                    fi;
-                    echo "The new package version ($PACKAGE_VER) is live, proceeding!";
-                    break;
-                done;
-                npm show $PACKAGE_NAME@$PACKAGE_VER # fails if the package is not available, succeeds if it is
-
-            - name: Commit the new theme version
-              uses: stefanzweifel/git-auto-commit-action@v5
-              with:
-                commit_message: 'chore: publish new version of @apify/docs-theme [skip ci]'
-                file_pattern: 'apify-docs-theme/package*.json'
-                commit_user_name: Apify Bot
-                commit_user_email: [email protected]
-                commit_author: Apify Bot <[email protected]>
+            -   name: Wait until the new theme version is available on npm
+                run: |
+                    cd $GITHUB_WORKSPACE/apify-docs-theme
+                    PACKAGE_JSON=$(cat package.json);
+                    PACKAGE_NAME=$(jq -r .name <(echo $PACKAGE_JSON));
+                    PACKAGE_VER=$(jq -r .version <(echo $PACKAGE_JSON));
+                    for i in $(seq 1 10); do
+                        EXIT_CODE=0;
+                        npm show $PACKAGE_NAME@$PACKAGE_VER || EXIT_CODE=1;
+                        if [[ $EXIT_CODE -eq 1 ]]; then
+                            echo "The new package version ($PACKAGE_VER) is not yet available, waiting 30 seconds...";
+                            sleep 30;
+                            continue;
+                        fi;
+                        echo "The new package version ($PACKAGE_VER) is live, proceeding!";
+                        break;
+                    done;
+                    npm show $PACKAGE_NAME@$PACKAGE_VER # fails if the package is not available, succeeds if it is
+
+            -   name: Commit the new theme version
+                uses: stefanzweifel/git-auto-commit-action@v5
+                with:
+                    commit_message: 'chore: publish new version of @apify/docs-theme [skip ci]'
+                    file_pattern: 'apify-docs-theme/package*.json'
+                    commit_user_name: Apify Bot
+                    commit_user_email: [email protected]
+                    commit_author: Apify Bot <[email protected]>
 
     rebuild-docs:
         needs: publish
@@ -109,10 +119,10 @@ jobs:
 
         runs-on: ubuntu-latest
         steps:
-          - env:
-              GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-            run: |
-                gh workflow run docs.yaml --repo ${{ matrix.repo }}
+            -   env:
+                    GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+                run: |
+                    gh workflow run docs.yaml --repo ${{ matrix.repo }}
 
     rebuild-python-docs:
         needs: publish
@@ -124,7 +134,7 @@ jobs:
 
         runs-on: ubuntu-latest
         steps:
-          - env:
-              GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-            run: |
-                gh workflow run build_and_deploy_docs.yaml --repo ${{ matrix.repo }}
+            -   env:
+                    GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+                run: |
+                    gh workflow run build_and_deploy_docs.yaml --repo ${{ matrix.repo }}