Skip to content

Commit 990e279

Browse files
B4nanrenovate[bot]barjin
authored
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 <jindrichbar@gmail.com>
1 parent 868b576 commit 990e279

File tree

255 files changed

+37745
-19423
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

255 files changed

+37745
-19423
lines changed

‎.github/workflows/apiary.yaml‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎.github/workflows/docs.yaml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,23 @@ jobs:
1818

1919
steps:
2020
- uses: actions/checkout@v4
21-
- name: Use Node.js 20
21+
- name: Use Node.js 22
2222
uses: actions/setup-node@v4
2323
with:
24-
node-version: 20
24+
node-version: 22
2525
cache: 'npm'
2626
cache-dependency-path: 'package-lock.json'
2727
always-auth: 'true'
2828
registry-url: 'https://npm.pkg.github.com/'
2929
scope: '@apify-packages'
3030

31+
- name: Enable corepack
32+
run: |
33+
corepack enable
34+
3135
- name: Build docs
3236
run: |
3337
npm ci --force
34-
npm update @apify/openapi
3538
npm run build
3639
env:
3740
APIFY_SIGNING_TOKEN: ${{ secrets.APIFY_SIGNING_TOKEN }}

‎.github/workflows/lychee.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,20 +11,23 @@ jobs:
1111
steps:
1212
- uses: actions/checkout@v4
1313

14-
- name: Use Node.js 20
14+
- name: Use Node.js 22
1515
uses: actions/setup-node@v4
1616
with:
17-
node-version: 20
17+
node-version: 22
1818
cache: 'npm'
1919
cache-dependency-path: 'package-lock.json'
2020
always-auth: 'true'
2121
registry-url: 'https://npm.pkg.github.com/'
2222
scope: '@apify-packages'
2323

24+
- name: Enable corepack
25+
run: |
26+
corepack enable
27+
2428
- name: Build docs
2529
run: |
2630
npm ci --force
27-
npm update @apify/openapi
2831
npm run build
2932
env:
3033
APIFY_SIGNING_TOKEN: ${{ secrets.APIFY_SIGNING_TOKEN }}

‎.github/workflows/openapi.yaml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Check OpenAPI specs
2+
3+
on:
4+
push:
5+
6+
#env:
7+
# APIFY_STAGING_TOKEN: ${{ secrets.APIFY_STAGING_TOKEN }}
8+
9+
jobs:
10+
build:
11+
name: Build the specification file
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- name: Use Node.js 22
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: 22
21+
cache: 'npm'
22+
cache-dependency-path: 'package-lock.json'
23+
registry-url: 'https://npm.pkg.github.com/'
24+
scope: '@apify-packages'
25+
26+
- name: Enable corepack
27+
run: |
28+
corepack enable
29+
30+
- name: Install Dependencies
31+
run: npm ci --force
32+
env:
33+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
34+
35+
- run: |
36+
npm ci
37+
npm run redoc:test
38+
39+
# TODO
40+
# - uses: actions/setup-python@v5
41+
# with:
42+
# python-version: '3.10'
43+
# - run: python -m pip install schemathesis==3.35.0

‎.github/workflows/publish-theme.yaml‎

Lines changed: 68 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,33 @@ on:
88

99
jobs:
1010
look_for_change:
11-
if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
12-
runs-on: ubuntu-latest
13-
outputs:
14-
theme_changed: ${{ steps.changed-theme-files.outputs.any_changed }}
15-
steps:
16-
- uses: actions/checkout@v4
17-
with:
18-
fetch-depth: 0
19-
20-
- name: Use Node.js 20
21-
uses: actions/setup-node@v4
22-
with:
23-
node-version: 20
24-
25-
- name: Check changes in theme
26-
id: changed-theme-files
27-
uses: tj-actions/changed-files@v45
28-
with:
29-
since_last_remote_commit: "true"
30-
files: |
31-
apify-docs-theme/**
11+
if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
12+
runs-on: ubuntu-latest
13+
outputs:
14+
theme_changed: ${{ steps.changed-theme-files.outputs.any_changed }}
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0
19+
20+
- name: Use Node.js 22
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: 22
24+
cache: 'npm'
25+
cache-dependency-path: 'package-lock.json'
26+
27+
- name: Enable corepack
28+
run: |
29+
corepack enable
30+
31+
- name: Check changes in theme
32+
id: changed-theme-files
33+
uses: tj-actions/changed-files@v45
34+
with:
35+
since_last_remote_commit: "true"
36+
files: |
37+
apify-docs-theme/**
3238
3339
publish:
3440
needs: look_for_change
@@ -39,14 +45,18 @@ jobs:
3945
with:
4046
token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
4147

42-
- name: Use Node.js 20
48+
- name: Use Node.js 22
4349
uses: actions/setup-node@v4
4450
with:
45-
node-version: 20
51+
node-version: 22
4652
cache: 'npm'
4753
cache-dependency-path: 'package-lock.json'
4854
always-auth: 'true'
4955

56+
- name: Enable corepack
57+
run: |
58+
corepack enable
59+
5060
- name: Setup git user and npm
5161
run: |
5262
git config --global user.name "Apify Release Bot"
@@ -70,33 +80,33 @@ jobs:
7080
GIT_USER: "barjin:${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}"
7181
GH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
7282

73-
- name: Wait until the new theme version is available on npm
74-
run: |
75-
cd $GITHUB_WORKSPACE/apify-docs-theme
76-
PACKAGE_JSON=$(cat package.json);
77-
PACKAGE_NAME=$(jq -r .name <(echo $PACKAGE_JSON));
78-
PACKAGE_VER=$(jq -r .version <(echo $PACKAGE_JSON));
79-
for i in $(seq 1 10); do
80-
EXIT_CODE=0;
81-
npm show $PACKAGE_NAME@$PACKAGE_VER || EXIT_CODE=1;
82-
if [[ $EXIT_CODE -eq 1 ]]; then
83-
echo "The new package version ($PACKAGE_VER) is not yet available, waiting 30 seconds...";
84-
sleep 30;
85-
continue;
86-
fi;
87-
echo "The new package version ($PACKAGE_VER) is live, proceeding!";
88-
break;
89-
done;
90-
npm show $PACKAGE_NAME@$PACKAGE_VER # fails if the package is not available, succeeds if it is
91-
92-
- name: Commit the new theme version
93-
uses: stefanzweifel/git-auto-commit-action@v5
94-
with:
95-
commit_message: 'chore: publish new version of @apify/docs-theme [skip ci]'
96-
file_pattern: 'apify-docs-theme/package*.json'
97-
commit_user_name: Apify Bot
98-
commit_user_email: my-github-actions-bot@example.org
99-
commit_author: Apify Bot <apify@apify.com>
83+
- name: Wait until the new theme version is available on npm
84+
run: |
85+
cd $GITHUB_WORKSPACE/apify-docs-theme
86+
PACKAGE_JSON=$(cat package.json);
87+
PACKAGE_NAME=$(jq -r .name <(echo $PACKAGE_JSON));
88+
PACKAGE_VER=$(jq -r .version <(echo $PACKAGE_JSON));
89+
for i in $(seq 1 10); do
90+
EXIT_CODE=0;
91+
npm show $PACKAGE_NAME@$PACKAGE_VER || EXIT_CODE=1;
92+
if [[ $EXIT_CODE -eq 1 ]]; then
93+
echo "The new package version ($PACKAGE_VER) is not yet available, waiting 30 seconds...";
94+
sleep 30;
95+
continue;
96+
fi;
97+
echo "The new package version ($PACKAGE_VER) is live, proceeding!";
98+
break;
99+
done;
100+
npm show $PACKAGE_NAME@$PACKAGE_VER # fails if the package is not available, succeeds if it is
101+
102+
- name: Commit the new theme version
103+
uses: stefanzweifel/git-auto-commit-action@v5
104+
with:
105+
commit_message: 'chore: publish new version of @apify/docs-theme [skip ci]'
106+
file_pattern: 'apify-docs-theme/package*.json'
107+
commit_user_name: Apify Bot
108+
commit_user_email: my-github-actions-bot@example.org
109+
commit_author: Apify Bot <apify@apify.com>
100110

101111
rebuild-docs:
102112
needs: publish
@@ -109,10 +119,10 @@ jobs:
109119

110120
runs-on: ubuntu-latest
111121
steps:
112-
- env:
113-
GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
114-
run: |
115-
gh workflow run docs.yaml --repo ${{ matrix.repo }}
122+
- env:
123+
GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
124+
run: |
125+
gh workflow run docs.yaml --repo ${{ matrix.repo }}
116126
117127
rebuild-python-docs:
118128
needs: publish
@@ -124,7 +134,7 @@ jobs:
124134

125135
runs-on: ubuntu-latest
126136
steps:
127-
- env:
128-
GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
129-
run: |
130-
gh workflow run build_and_deploy_docs.yaml --repo ${{ matrix.repo }}
137+
- env:
138+
GITHUB_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
139+
run: |
140+
gh workflow run build_and_deploy_docs.yaml --repo ${{ matrix.repo }}

0 commit comments

Comments
 (0)