jaykay12 commented on code in PR #5201: URL: https://github.com/apache/solr/pull/5201#discussion_r4553125312
########## gradle/libs.versions.toml: ########## @@ -157,6 +157,7 @@ nodegradle-node = "7.1.0" nodejs = "22.18.0" onnx = "1.29.0" openapi = "7.25.0" +scalar-api-reference = "1.46.4" Review Comment: [for-my-knowledge] where do i verify that this is the most latest available stable version? can you help me with the gradle dependency page of this artifact. ########## solr/solr-ref-guide/modules/getting-started/pages/solr-admin-ui.adoc: ########## @@ -47,6 +47,12 @@ The path to the Solr Admin UI given above is `\http://hostname:port/solr`, which A convenience redirect is also supported, so simply accessing the Admin UI at `\http://hostname:port/` will also redirect to `\http://hostname:port/solr/#/`. ==== +=== API Explorer + +The *API Explorer* item in the Admin UI's left-hand navigation opens interactive documentation for Solr's v2 API. +It renders the OpenAPI specification bundled with Solr and lets you browse endpoints and send requests to the running instance. +Requests use the instance's authentication and authorization rules and can modify its data or configuration. Review Comment: I see other sections also have a screenshot of their UI, should we also keep home page screenshot of the api explorer in this section. something similar to this should work? <img width="1465" height="777" alt="Screenshot 2026-11-13 at 12 58 44 AM" src="https://github.com/user-attachments/assets/7141bb11-166f-4d99-a60e-d3ab8b31bc71" /> ########## solr/webapp/scalar/build.gradle.kts: ########## @@ -0,0 +1,59 @@ +/* + * 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. + */ + +import com.github.gradle.node.npm.task.NpmTask + +// Downloads the pre-built @scalar/api-reference browser bundle via npm, for :solr:webapp to +// include in the war. Keeps the large generated bundle out of source control, unlike a +// hand-vendored copy. + +plugins { + id("base") + alias(libs.plugins.nodegradle.node) +} + +description = "Downloads the Scalar API Reference browser bundle for the Admin UI's API Explorer" + +val scalarBundleDir = layout.buildDirectory.dir("scalarBundle").get().asFile Review Comment: I am not fully sure/confident yet on the licenses stuff, but my local review agent flagged this > The war build now needs a live npm download, so offline and air-gapped builds fail. standalone.js bundles many third-party libs, but NOTICE.txt covers only Scalar, and the license tooling doesn’t see npm packages. Please see, if this is something that needs to be acted upon. ########## gradle/libs.versions.toml: ########## @@ -157,6 +157,7 @@ nodegradle-node = "7.1.0" nodejs = "22.18.0" onnx = "1.29.0" openapi = "7.25.0" +scalar-api-reference = "1.46.4" Review Comment: [major] this breaks the alphabetical order that we maintain in this file, lets move this entry to the right place. ########## solr/webapp/web/css/angular/menu.css: ########## @@ -262,6 +262,8 @@ limitations under the License. #menu #threads.global p a { background-image: url( ../../img/ico/ui-accordion.png ); } +#menu #api-explorer.global p a { background-image: url( ../../img/ico/openapi.png ); } Review Comment: <img width="139" height="399" alt="Screenshot 2026-11-13 at 1 04 45 AM" src="https://github.com/user-attachments/assets/5d12271d-b0d8-4d16-a1f3-475aa86ac1e7" /> personally, the openAPI icon looks little different from how our exising icons are. [my-doubt] do we have any designer in our community as well, who helps us in making these UI/UX changes. ########## solr/solr-ref-guide/modules/getting-started/pages/solr-admin-ui.adoc: ########## @@ -47,6 +47,12 @@ The path to the Solr Admin UI given above is `\http://hostname:port/solr`, which A convenience redirect is also supported, so simply accessing the Admin UI at `\http://hostname:port/` will also redirect to `\http://hostname:port/solr/#/`. ==== +=== API Explorer Review Comment: should we be refreshing the base image on this adoc as well to keep the docs consistent with latest state? image::solr-admin-ui/dashboard.png[image,height=400] ? ########## solr/webapp/web/libs/scalar/index.html: ########## @@ -0,0 +1,36 @@ +<!-- +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. +--> +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Solr V2 API Explorer</title> +</head> +<body> + <!-- + Loaded in an iframe by the Admin UI's API Explorer page, rather than mounted directly + into the Angular app: Scalar manages its own URL hash for deep-linking to operations, + which conflicts with AngularJS's ngRoute (both rewrite window.location.hash), causing an + infinite digest/navigation loop. A dedicated document gives Scalar its own window and + history, with no shared hash to contend over. + --> + <div id="app"></div> + <script src="standalone.js" charset="UTF-8"></script> Review Comment: [for-my-knowledge] we dont have this file: 'standalong.js' in our codebase. how this linking works then? ########## dev-docs/local-api-explorer.adoc: ########## @@ -0,0 +1,29 @@ += Browsing the V2 API with the API Explorer + +Solr's v2 (JAX-RS) API is described by an OpenAPI spec generated at build time +from the annotated interfaces in `solr/api/src/java/.../client/api/endpoint`. +The API Explorer is bundled in the Admin UI and renders the generated spec using Scalar. +It's loaded in an iframe from `solr/webapp/web/libs/scalar/index.html` rather than mounted +directly into the Angular app: Scalar manages its own URL hash for deep-linking to operations, +which conflicts with AngularJS's `ngRoute` (both rewrite `window.location.hash`), causing an +infinite digest/navigation loop. A dedicated document/window avoids the conflict entirely. + +== Usage + +Build and start a local Solr with `./gradlew dev` and `bin/solr start -c`. +Open the *API Explorer* item in the Admin UI's left nav to browse endpoints and send requests. Review Comment: Lets add 1 or 2 screenshots as well? ########## solr/core/src/java/org/apache/solr/servlet/LoadAdminUiServlet.java: ########## @@ -72,7 +72,10 @@ public void doGet(HttpServletRequest request, HttpServletResponse response) thro HttpHeaders.CONTENT_SECURITY_POLICY, "default-src 'none'; base-uri 'none'; connect-src " + connectSrc - + "; form-action 'self'; font-src 'self'; frame-ancestors 'none'; img-src 'self' data:; media-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; worker-src 'self';"); + // frame-src: the Admin UI's API Explorer loads a same-origin page in an + // iframe (Scalar manages its own URL hash for deep-linking, which conflicts + // with AngularJS's ngRoute if mounted directly into the app instead). Review Comment: [ques] is this comment suited here? or should be in some dev docs? if i am right, we are adding frame-src 'self'; entry here. there were many entries here already, so just adding for 1 we should avoid. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
