(pulsar-site) 02/02: Add rest_api_spec_dir token for REST API spec file links

[lh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git

commit 58ff852580eea1de0ed1a6bd1f9f9490f893f2ec
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Thu Jun 18 01:50:47 2026 +0300

    Add rest_api_spec_dir token for REST API spec file links
    
    Resolve to /openapi/<version>/ for master/5.0.0+ docs and /swagger/<version>/
    for earlier docs, so the "REST API JSON files" link in admin-api-tutorial.md
    points at the correct static tree per version.
---
 docs/admin-api-tutorial.md    |  2 +-
 src/config/pulsarVariables.ts | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/admin-api-tutorial.md b/docs/admin-api-tutorial.md
index e1f64314014..590267911e5 100644
--- a/docs/admin-api-tutorial.md
+++ b/docs/admin-api-tutorial.md
@@ -37,7 +37,7 @@ If you have enabled authentication, you need to provide an auth configuration to
 
 You can find details for the REST API exposed by Pulsar brokers in the [REST API doc](pathname:///admin-rest-api/?version=@pulsar:rest_api_version@).
 
-If you want to test REST APIs in postman, you can use the REST API JSON files [here](pathname:///swagger/).
+If you want to test REST APIs in postman, you can use the REST API JSON files [here](pathname://@pulsar:rest_api_spec_dir@).
 
 </TabItem>
 <TabItem value="Java">
diff --git a/src/config/pulsarVariables.ts b/src/config/pulsarVariables.ts
index a220e5981f8..a3165a5d145 100644
--- a/src/config/pulsarVariables.ts
+++ b/src/config/pulsarVariables.ts
@@ -141,6 +141,20 @@ export function referenceVersion(version: string): string {
   return `${v.major}.${v.minor}.x`;
 }
 
+// Pulsar 5.0.0+/master publish OpenAPI 3 REST API docs under /openapi/; earlier
+// releases keep their Swagger 2.0 docs under /swagger/. Mirrors usesOpenApi3()
+// in src/pages/RestApi/RestApi.tsx and src/server/remarkPlugins/swagger/index.ts.
+export function usesOpenApi3(version: string): boolean {
+  if (version === "master") return true;
+  const v = semver.coerce(version);
+  return v !== null && v.major >= 5;
+}
+
+export function restApiSpecDir(restApiVersion: string): string {
+  const root = usesOpenApi3(restApiVersion) ? "openapi" : "swagger";
+  return `/${root}/${restApiVersion}/`;
+}
+
 /**
  * Token → replacement value for a given version key.
  * `"current"` → next/current docs; any other string is an origin version
@@ -159,6 +173,11 @@ export function referenceVersion(version: string): string {
  * docs it resolves to `master` (the in-development API), since the REST API viewer keys
  * the in-development spec under `master` rather than a numbered release. Versioned docs
  * resolve it to their concrete release, matching `version_number`.
+ *
+ * `rest_api_spec_dir` is the static directory that holds the raw REST API spec JSON
+ * files for the doc's version (e.g. `pathname://@pulsar:rest_api_spec_dir@`). Pulsar
+ * 5.0.0+/master docs resolve to `/openapi/<version>/` (OpenAPI 3); earlier docs resolve
+ * to `/swagger/<version>/` (Swagger 2.0).
  */
 export function resolveTokens(versionKey: string, referenceLatest = false): Map<string, string> {
   const isCurrent = versionKey === "current";
@@ -192,6 +211,7 @@ export function resolveTokens(versionKey: string, referenceLatest = false): Map<
     ["javadoc:pulsar-functions", javadocVersionUrl(originVersion, "pulsar-functions")],
     ["offloader_release_url", offloaderReleaseUrl(resolvedVersion)],
     ["presto_pulsar_connector_release_url", prestoPulsarReleaseUrl(resolvedVersion)],
+    ["rest_api_spec_dir", restApiSpecDir(restApiVersion)],
     ["rest_api_version", restApiVersion],
     ["rpm:client-debuginfo", rpmDistUrl(resolvedVersion, "-debuginfo")],
     ["rpm:client-devel", rpmDistUrl(resolvedVersion, "-devel")],