diff --git a/changelog/unreleased/SOLR-17395-elements-ui.yml b/changelog/unreleased/SOLR-17395-elements-ui.yml new file mode 100644 index 000000000000..3c38221c0527 --- /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: added +authors: + - name: Eric Pugh +links: + - name: SOLR-17395 + url: https://issues.apache.org/jira/browse/SOLR-17395 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..18acbbd0f138 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}/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" 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..e0bf1aa47edd 100644 --- a/solr/solr-ref-guide/playbook.template.yml +++ b/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}' 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..23f9d41a0e13 --- /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