Render OpenAPI spec as Ref Guide page

changelog/unreleased/SOLR-17395-elements-ui.yml

@@ -0,0 +1,7 @@
+title: Add API Reference to Ref Guide generated from OpenAPI specfication file.
+type: added
+authors:
+  - name: Eric Pugh
+links:
+  - name: SOLR-17395
+    url: https://issues.apache.org/jira/browse/SOLR-17395

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"

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:

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:

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}/ui-src/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"
 

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[]

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
+
+++++
+<elements-api
+  apiDescriptionUrl="./_attachments/solr-openapi.json"
+  router="hash"
+  layout="stacked"
+  hideExport="true"
+  logo="https://solr.apache.org/theme/images/logo.svg"
+/>
+++++

solr/solr-ref-guide/playbook.template.yml

@@ -41,6 +41,12 @@ 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
+    - 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:
   clean: true
   dir: '${site_dir}'

solr/solr-ref-guide/ui-src/layouts/api-reference.hbs

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+{{> head defaultPageTitle='Untitled'}}
+    <script src="{{{uiRootPath}}}/js/vendor/elements-web-components.min.js"></script>
+    <link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/elements-styles.min.css">
+  </head>
+  <body class="article api-reference">
+{{> header}}
+{{> body}}
+{{> footer}}
+  </body>
+</html>