This is an automated email from the ASF dual-hosted git repository.
kayx23 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new ed68e71fe71 feat(docs): render historical Admin APIs with Scalar
(#2145)
ed68e71fe71 is described below
commit ed68e71fe71eb58a563b6a41c42eff255d54fe5f
Author: Traky Deng <[email protected]>
AuthorDate: Fri Oct 30 15:31:58 2026 +0800
feat(docs): render historical Admin APIs with Scalar (#2145)
---
doc/src/components/AdminApiReference/index.tsx | 6 +++---
next/scripts/check-admin-api-sources.mjs | 2 +-
next/tests/admin-api/README.md | 23 ++++++++++++++---------
next/tests/admin-api/admin-api.spec.mjs | 8 +++++++-
next/tests/admin-api/source-fixtures.json | 15 +++++++++++++++
scripts/sync-docs.js | 5 +++++
6 files changed, 45 insertions(+), 14 deletions(-)
diff --git a/doc/src/components/AdminApiReference/index.tsx
b/doc/src/components/AdminApiReference/index.tsx
index 5f8ece94d61..5240145fb65 100644
--- a/doc/src/components/AdminApiReference/index.tsx
+++ b/doc/src/components/AdminApiReference/index.tsx
@@ -16,9 +16,9 @@ const AdminApiReference = ({ path, children }: Props):
JSX.Element => {
const root = useRef<HTMLDivElement>(null);
const match = path.match(/^(\/zh)?\/docs\/apisix\/([^/]+)\/admin-api\/?$/);
const prefix = match?.[1] ?? '';
- // Roll out the unreleased master contract first. Release archives remain on
- // Markdown until their branch-specific specifications are merged and wired.
- const supported = ['next'];
+ // Enable only versions with a merged, branch-specific Admin API contract.
+ // Other archives keep their existing Markdown reference.
+ const supported = ['3.16', '3.17', '3.18', 'next'];
const version = supported.includes(match?.[2]) ? match?.[2] : undefined;
const zh = prefix === '/zh';
const specUrl = `/assets/openapi/apisix/${version}/admin-api.json`;
diff --git a/next/scripts/check-admin-api-sources.mjs
b/next/scripts/check-admin-api-sources.mjs
index 94fe52e9291..abc2ce58c65 100644
--- a/next/scripts/check-admin-api-sources.mjs
+++ b/next/scripts/check-admin-api-sources.mjs
@@ -7,7 +7,7 @@ import { isAdminApiSpec } from '../../shared/admin-api-spec.ts';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
'../..');
const assets = process.argv[2] ?? path.join(root,
'doc/static/assets/openapi/apisix');
-const required = ['next'];
+const required = ['3.16', '3.17', '3.18', 'next'];
let failed = false;
required.forEach((version) => {
const ref = version === 'next' ? 'master' : `release/${version}`;
diff --git a/next/tests/admin-api/README.md b/next/tests/admin-api/README.md
index 6cfd4fd0120..e8a7e6421ee 100644
--- a/next/tests/admin-api/README.md
+++ b/next/tests/admin-api/README.md
@@ -1,7 +1,7 @@
# Admin API production checks
This suite needs the assembled production site: the current page is Astro,
-while the Next page is Docusaurus. Serve that output, then run:
+while the release archives and Next are Docusaurus. Serve that output, then
run:
```sh
cd next
@@ -9,7 +9,8 @@ ADMIN_API_BASE_URL=http://127.0.0.1:4322 npm run test:admin-api
```
The existing Playwright configuration runs desktop and mobile Chromium. The
-suite checks both locales for the current 3.19 page and Next. Success tests
+suite checks both locales for the current 3.19 page, 3.16–3.18 archives, and
+Next. Success tests
require their actual synced canonical English specifications; they must not be
reported as passed by substituting another release's JSON. Failure tests
intercept requests to exercise missing, malformed, failed and timed-out JSON,
@@ -21,12 +22,13 @@ sources; it is separate from production builds, which
retain Markdown when a
source is absent or invalid. Sync and build from these apache/apisix refs:
- current: `release/3.19`
+- archives: `release/3.16`, `release/3.17`, and `release/3.18`
- Next: `master`
-The Next sync copies `docs/en/latest/admin-api.json` byte-for-byte to
-`doc/static/assets/openapi/apisix/next/admin-api.json`. Both locales use that
-same asset. Missing sources remove stale assets and retain Markdown. Release
-archives continue using Markdown until their own source and rendering PRs land.
+The archive and Next syncs copy `docs/en/latest/admin-api.json` byte-for-byte
to
+`doc/static/assets/openapi/apisix/<version>/admin-api.json`. Both locales use
+the same asset for each version. Missing sources remove stale assets and retain
+Markdown. Other release archives continue using Markdown.
The assembled deployment already ships `doc/build/assets`, so no external
specification request or additional deployment copy step is needed.
@@ -38,9 +40,9 @@ node --test shared/admin-api-spec.test.mjs
scripts/lib/admin-api.test.js
## Immutable canonical validation fixtures
-`source-fixtures.json` pins the merged master specification in `apache/apisix`
-for reproducible tests. Production synchronization continues to use
-`apache/apisix:master`.
+`source-fixtures.json` pins the merged release and master specifications in
+`apache/apisix` for reproducible tests. Production synchronization continues
+to use the corresponding Apache branches.
After preparing generated static assets from those exact commits, check them
without fetching or changing any content:
@@ -51,6 +53,9 @@ node next/scripts/check-admin-api-fixtures.mjs
/path/to/apisix-fixture-checkout
| Canonical Apache ref | Immutable source |
| --- | --- |
+| `release/3.16` |
https://github.com/apache/apisix/commit/ae0dc4a842b3855a8ac71db97e659231d5592167
|
+| `release/3.17` |
https://github.com/apache/apisix/commit/9fae9b644357281976463626c624064c0464b5a1
|
+| `release/3.18` |
https://github.com/apache/apisix/commit/8d7e45597a065472ba33672581fb7fbafff523ca
|
| `master` |
https://github.com/apache/apisix/commit/88a41b7f30da10072294ae48b1d1d7369452b1ac
|
Run the fixture check against an `apache/apisix` checkout containing the pinned
diff --git a/next/tests/admin-api/admin-api.spec.mjs
b/next/tests/admin-api/admin-api.spec.mjs
index 29938dd1320..e3d16d1ec18 100644
--- a/next/tests/admin-api/admin-api.spec.mjs
+++ b/next/tests/admin-api/admin-api.spec.mjs
@@ -19,7 +19,7 @@ test.beforeEach(async ({ page }, testInfo) => {
}));
});
-const versions = ['', 'next/'];
+const versions = ['', '3.16/', '3.17/', '3.18/', 'next/'];
['', '/zh'].forEach((locale) => {
versions.forEach((version) => {
const route = `${locale}/docs/apisix/${version}admin-api/`;
@@ -106,4 +106,10 @@ const versions = ['', 'next/'];
});
});
});
+
+ test(`${locale}/docs/apisix/3.15/admin-api/ remains Markdown-only`, async ({
page }) => {
+ await page.goto(`${locale}/docs/apisix/3.15/admin-api/`, { waitUntil:
'domcontentloaded' });
+ await expect(page.locator('#admin-api-openapi')).toHaveCount(0);
+ await expect(page.locator('article')).toBeVisible();
+ });
});
diff --git a/next/tests/admin-api/source-fixtures.json
b/next/tests/admin-api/source-fixtures.json
index 05da3ce47d5..92a8143b1d0 100644
--- a/next/tests/admin-api/source-fixtures.json
+++ b/next/tests/admin-api/source-fixtures.json
@@ -1,4 +1,19 @@
[
+ {
+ "version": "3.16",
+ "canonicalRef": "release/3.16",
+ "commit": "ae0dc4a842b3855a8ac71db97e659231d5592167"
+ },
+ {
+ "version": "3.17",
+ "canonicalRef": "release/3.17",
+ "commit": "9fae9b644357281976463626c624064c0464b5a1"
+ },
+ {
+ "version": "3.18",
+ "canonicalRef": "release/3.18",
+ "commit": "8d7e45597a065472ba33672581fb7fbafff523ca"
+ },
{
"version": "next",
"canonicalRef": "master",
diff --git a/scripts/sync-docs.js b/scripts/sync-docs.js
index 06b7ec17666..a80afcb757c 100644
--- a/scripts/sync-docs.js
+++ b/scripts/sync-docs.js
@@ -26,6 +26,7 @@ const projectReleases = {};
// apisix-2.10.x) and orphaned 403 landing dirs. apisix itself is curated
// separately in config/apisix-versions.js. Increase this for a wider window.
const SUBPROJECT_VERSIONS_TO_KEEP = 1;
+const APISIX_SCALAR_ARCHIVES = new Set(['3.16', '3.17', '3.18']);
const tasks = new Listr([
{
@@ -397,6 +398,10 @@ function extractDocsVersionTasks(project, version) {
const enTargetDocs =
`${websitePath}/docs-${projectName}_versioned_docs/version-${displayVersionName}`;
const zhTargetDocs =
`${websitePath}/i18n/zh/docusaurus-plugin-content-docs-docs-${projectName}/version-${displayVersionName}`;
+ if (projectName === 'apisix' && APISIX_SCALAR_ARCHIVES.has(version)) {
+ await publishAdminApiSpec(enSrcDocs, version,
`${websitePath}/static`);
+ }
+
await Promise.allSettled([
copyDocs(enSrcDocs, enTargetDocs)
.then(() => replaceMDElements(projectName, [enTargetDocs],
branchName, 'en'))
