From c818db3824dc2f26b3859556cd6f3ab10d3182ae Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Sat, 18 Apr 2026 15:30:05 +0100 Subject: [PATCH 1/5] Render OpenAPI spec as Ref Guide page --- gradle/libs.versions.toml | 2 + solr/solr-ref-guide/antora.template.yml | 1 + solr/solr-ref-guide/antora.yml | 1 + solr/solr-ref-guide/build.gradle | 42 +++++++++++++++++++ .../api-reference/api-reference-nav.adoc | 19 +++++++++ .../modules/api-reference/pages/v2-api.adoc | 31 ++++++++++++++ solr/solr-ref-guide/playbook.template.yml | 2 + 7 files changed, 98 insertions(+) create mode 100644 solr/solr-ref-guide/modules/api-reference/api-reference-nav.adoc create mode 100644 solr/solr-ref-guide/modules/api-reference/pages/v2-api.adoc diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 0bcff24a4457..dadfc84f31f7 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -158,6 +158,8 @@ ktor = "3.2.2" langchain4j-bom = "1.9.1" # @keep Link checker version used in ref-guide link-checker = "1.4.2" +# @keep Stoplight Elements version used in ref-guide for OpenAPI rendering +stoplight-elements = "8.4.0" littlerobots-versioncatalogupdate = "0.8.5" lmax-disruptor = "4.0.0" logchange = "1.19.13" diff --git a/solr/solr-ref-guide/antora.template.yml b/solr/solr-ref-guide/antora.template.yml index 3f1e8ef816d5..e3b9e8ab58c1 100644 --- a/solr/solr-ref-guide/antora.template.yml +++ b/solr/solr-ref-guide/antora.template.yml @@ -32,6 +32,7 @@ nav: - modules/query-guide/querying-nav.adoc - modules/upgrade-notes/upgrade-nav.adoc - modules/how-to-contribute/how-to-contribute-nav.adoc +- modules/api-reference/api-reference-nav.adoc # The asciidoc attributes must be the last entry in this file asciidoc: diff --git a/solr/solr-ref-guide/antora.yml b/solr/solr-ref-guide/antora.yml index 50cce466b402..ca60ecfd38ed 100644 --- a/solr/solr-ref-guide/antora.yml +++ b/solr/solr-ref-guide/antora.yml @@ -32,6 +32,7 @@ nav: - modules/query-guide/querying-nav.adoc - modules/upgrade-notes/upgrade-nav.adoc - modules/how-to-contribute/how-to-contribute-nav.adoc +- modules/api-reference/api-reference-nav.adoc # The asciidoc attributes must be the last entry in this file asciidoc: diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle index 5b53514d698a..7e2bb9de79c5 100644 --- a/solr/solr-ref-guide/build.gradle +++ b/solr/solr-ref-guide/build.gradle @@ -60,11 +60,13 @@ configurations { officialPlaybook localPlaybook localJavadocs + openapiSpec } dependencies { localJavadocs project(path: ":solr:documentation", configuration: 'javadocs') localJavadocs project(path: ":solr:documentation", configuration: 'site') + openapiSpec project(path: ":solr:api", configuration: 'openapiSpec') } ext { @@ -253,6 +255,15 @@ task downloadAsciidoctorTabsExtension(type: NpmTask) { outputs.dir("${project.ext.nodeProjectDir}/node_modules/@asciidoctor/tabs") } +task downloadStoplightElements(type: NpmTask) { + group = 'Build Dependency Download' + description "Download Stoplight Elements bundle for OpenAPI rendering in the ref-guide." + args = ["install", "@stoplight/elements@${libs.versions.stoplight.elements.get()}"] + + inputs.property("stoplight-elements version", libs.versions.stoplight.elements.get()) + outputs.dir("${project.ext.nodeProjectDir}/node_modules/@stoplight/elements") +} + task downloadAntora { group = 'Build Dependency Download' description "Download all Antora build dependencies for site generation." @@ -262,6 +273,7 @@ task downloadAntora { dependsOn tasks.downloadAntoraLunrExtension dependsOn tasks.downloadAsciidoctorMathjaxExtension dependsOn tasks.downloadAsciidoctorTabsExtension + dependsOn tasks.downloadStoplightElements } task downloadLinkValidator(type: NpmTask) { @@ -384,12 +396,42 @@ task setupLocalSiteStagingDir(type: Sync) { into project.ext.siteStagingDir } +task stageOpenApiAssets(type: Copy) { + group = 'Site - Local' + description "Copies the OpenAPI spec and supplemental UI files into the site staging directory." + + dependsOn configurations.openapiSpec + dependsOn tasks.setupLocalSiteStagingDir + + // Copy the OpenAPI spec JSON into the api-reference module's attachments + from(configurations.openapiSpec) { + rename { "solr-openapi.json" } + into "modules/api-reference/attachments" + } + + into project.ext.siteStagingDir +} + +// Copy the custom layout into nodeProjectDir so ~+ paths in the playbook can resolve it +task stageSupplementalUIAssets(type: Copy) { + group = 'Site - Local' + description "Copies supplemental UI assets (layouts, etc.) into the node project dir for playbook resolution." + + from("${projectDir}/supplemental-ui/layouts/api-reference.hbs") { + into "supplemental-ui/layouts" + } + + into project.ext.nodeProjectDir +} + task buildLocalAntoraSite(type: NpxTask) { group = 'Site - Local' description "Creates a local build of the ref-guide." dependsOn tasks.downloadAntora dependsOn tasks.setupLocalSiteStagingDir + dependsOn tasks.stageOpenApiAssets + dependsOn tasks.stageSupplementalUIAssets command = "antora" diff --git a/solr/solr-ref-guide/modules/api-reference/api-reference-nav.adoc b/solr/solr-ref-guide/modules/api-reference/api-reference-nav.adoc new file mode 100644 index 000000000000..c4b7817be92a --- /dev/null +++ b/solr/solr-ref-guide/modules/api-reference/api-reference-nav.adoc @@ -0,0 +1,19 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +.API Reference +* xref:v2-api.adoc[] diff --git a/solr/solr-ref-guide/modules/api-reference/pages/v2-api.adoc b/solr/solr-ref-guide/modules/api-reference/pages/v2-api.adoc new file mode 100644 index 000000000000..a846590b4932 --- /dev/null +++ b/solr/solr-ref-guide/modules/api-reference/pages/v2-api.adoc @@ -0,0 +1,31 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + += Solr v2 API Reference +:page-layout: api-reference +:page-show-toc: false +:role: hide-sidebar + +++++ + +++++ diff --git a/solr/solr-ref-guide/playbook.template.yml b/solr/solr-ref-guide/playbook.template.yml index ad283d03392e..39b755507b8f 100644 --- a/solr/solr-ref-guide/playbook.template.yml +++ b/solr/solr-ref-guide/playbook.template.yml @@ -41,6 +41,8 @@ ui: supplemental_files: - path: js/vendor/tabs.js contents: ~+/node_modules/@asciidoctor/tabs/dist/js/tabs.js + - path: js/vendor/elements-web-components.min.js + contents: ~+/node_modules/@stoplight/elements/web-components.min.js output: clean: true dir: '${site_dir}' From 0f2b9f0ed74cc73d80bf478aea33ed65aa1de88b Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Sat, 18 Apr 2026 15:42:06 +0100 Subject: [PATCH 2/5] Now working, fix up links --- solr/solr-ref-guide/build.gradle | 2 +- solr/solr-ref-guide/playbook.template.yml | 4 +++- .../solr-ref-guide/ui-src/layouts/api-reference.hbs | 13 +++++++++++++ 3 files changed, 17 insertions(+), 2 deletions(-) create mode 100644 solr/solr-ref-guide/ui-src/layouts/api-reference.hbs diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle index 7e2bb9de79c5..18acbbd0f138 100644 --- a/solr/solr-ref-guide/build.gradle +++ b/solr/solr-ref-guide/build.gradle @@ -417,7 +417,7 @@ task stageSupplementalUIAssets(type: Copy) { group = 'Site - Local' description "Copies supplemental UI assets (layouts, etc.) into the node project dir for playbook resolution." - from("${projectDir}/supplemental-ui/layouts/api-reference.hbs") { + from("${projectDir}/ui-src/layouts/api-reference.hbs") { into "supplemental-ui/layouts" } diff --git a/solr/solr-ref-guide/playbook.template.yml b/solr/solr-ref-guide/playbook.template.yml index 39b755507b8f..d4c0c3f7216d 100644 --- a/solr/solr-ref-guide/playbook.template.yml +++ b/solr/solr-ref-guide/playbook.template.yml @@ -42,7 +42,9 @@ ui: - path: js/vendor/tabs.js contents: ~+/node_modules/@asciidoctor/tabs/dist/js/tabs.js - path: js/vendor/elements-web-components.min.js - contents: ~+/node_modules/@stoplight/elements/web-components.min.js + contents: ~+/node_modules/@stoplight/elements/web-components.min.js + - path: layouts/api-reference.hbs + contents: ~+/supplemental-ui/layouts/api-reference.hbs output: clean: true dir: '${site_dir}' diff --git a/solr/solr-ref-guide/ui-src/layouts/api-reference.hbs b/solr/solr-ref-guide/ui-src/layouts/api-reference.hbs new file mode 100644 index 000000000000..bf9c86759f9c --- /dev/null +++ b/solr/solr-ref-guide/ui-src/layouts/api-reference.hbs @@ -0,0 +1,13 @@ + + + +{{> head defaultPageTitle='Untitled'}} + + + + +{{> header}} +{{> body}} +{{> footer}} + + \ No newline at end of file From 14ac5456124e5d2e61ac19b37d5376994ed5ea36 Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Sat, 18 Apr 2026 21:03:25 -0400 Subject: [PATCH 3/5] Package css internally to Solr --- solr/solr-ref-guide/playbook.template.yml | 2 ++ solr/solr-ref-guide/ui-src/layouts/api-reference.hbs | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/solr/solr-ref-guide/playbook.template.yml b/solr/solr-ref-guide/playbook.template.yml index d4c0c3f7216d..e0bf1aa47edd 100644 --- a/solr/solr-ref-guide/playbook.template.yml +++ b/solr/solr-ref-guide/playbook.template.yml @@ -43,6 +43,8 @@ ui: contents: ~+/node_modules/@asciidoctor/tabs/dist/js/tabs.js - path: js/vendor/elements-web-components.min.js contents: ~+/node_modules/@stoplight/elements/web-components.min.js + - path: css/vendor/elements-styles.min.css + contents: ~+/node_modules/@stoplight/elements/styles.min.css - path: layouts/api-reference.hbs contents: ~+/supplemental-ui/layouts/api-reference.hbs output: diff --git a/solr/solr-ref-guide/ui-src/layouts/api-reference.hbs b/solr/solr-ref-guide/ui-src/layouts/api-reference.hbs index bf9c86759f9c..23f9d41a0e13 100644 --- a/solr/solr-ref-guide/ui-src/layouts/api-reference.hbs +++ b/solr/solr-ref-guide/ui-src/layouts/api-reference.hbs @@ -3,7 +3,7 @@ {{> head defaultPageTitle='Untitled'}} - + {{> header}} From 396600bf9216ba1be0c60768a2cedc8fcaacdf7b Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Sat, 18 Apr 2026 21:03:30 -0400 Subject: [PATCH 4/5] document change --- changelog/unreleased/SOLR-17395-elements-ui.yml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 changelog/unreleased/SOLR-17395-elements-ui.yml diff --git a/changelog/unreleased/SOLR-17395-elements-ui.yml b/changelog/unreleased/SOLR-17395-elements-ui.yml new file mode 100644 index 000000000000..9a3020c3a682 --- /dev/null +++ b/changelog/unreleased/SOLR-17395-elements-ui.yml @@ -0,0 +1,7 @@ +title: Add API Reference to Ref Guide generated from OpenAPI specfication file. +type: +authors: + - name: Eric Pugh +links: + - name: SOLR-17395 + url: https://issues.apache.org/jira/browse/SOLR-17395 From f356027038d4dbc4b88419b17921af63370b1c3d Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Sun, 19 Apr 2026 10:12:12 -0400 Subject: [PATCH 5/5] and add type.. adminstrivia --- changelog/unreleased/SOLR-17395-elements-ui.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/unreleased/SOLR-17395-elements-ui.yml b/changelog/unreleased/SOLR-17395-elements-ui.yml index 9a3020c3a682..3c38221c0527 100644 --- a/changelog/unreleased/SOLR-17395-elements-ui.yml +++ b/changelog/unreleased/SOLR-17395-elements-ui.yml @@ -1,5 +1,5 @@ title: Add API Reference to Ref Guide generated from OpenAPI specfication file. -type: +type: added authors: - name: Eric Pugh links: