HDDS-10684. Add Swagger API for Recon as a Docusaurus page.

.yamllint.yml

@@ -22,6 +22,8 @@ ignore:
 - node_modules
 - "**/static/docs"
 - build
+- static/recon-api.yaml
+- "**/recon-api.yaml"
 
 rules:
   anchors: enable

docs/05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.mdx

@@ -0,0 +1,9 @@
+# Recon REST API
+
+import SwaggerUI from '@site/src/components/SwaggerUI';
+
+Ozone Recon's public **REST API** follows the [OpenAPI specification](https://www.openapis.org/), and is documented below.
+
+The API is defined in the [recon-api.yaml](/recon-api.yaml) OpenAPI specification file and is available under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html).
+
+<SwaggerUI spec="/recon-api.yaml" defaultServer="http://localhost:9888" />

package.json

@@ -27,7 +27,8 @@
     "prism-react-renderer": "^2.4.1",
     "react": "^18.3.1",
     "react-bootstrap-icons": "^1.11.5",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "swagger-ui-react": "^5.31.0"
   },
   "devDependencies": {
     "@cspell/dict-docker": "^1.1.12",

src/components/SwaggerUI/index.js

@@ -0,0 +1,113 @@
+/*
+ * 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 React, { useState, useRef, useEffect } from 'react';
+import SwaggerUI from 'swagger-ui-react';
+import 'swagger-ui-react/swagger-ui.css';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import styles from './styles.module.css';
+
+export default function SwaggerUIComponent({ spec, defaultServer }) {
+  const specUrl = useBaseUrl(spec);
+  const [serverUrl, setServerUrl] = useState(defaultServer || 'http://localhost:9888');
+  const [apiVersion, setApiVersion] = useState('v1');
+  const [appliedServerUrl, setAppliedServerUrl] = useState(defaultServer || 'http://localhost:9888');
+  const [appliedApiVersion, setAppliedApiVersion] = useState('v1');
+  const swaggerSystemRef = useRef(null);
+
+  // Update the server URL in Swagger only when applied values change
+  useEffect(() => {
+    if (swaggerSystemRef.current) {
+      const spec = swaggerSystemRef.current.getState().getIn(['spec', 'json']);
+      if (spec) {
+        // Construct full URL: {serverUrl}/api/{version}/
+        const baseUrl = appliedServerUrl.endsWith('/') ? appliedServerUrl.slice(0, -1) : appliedServerUrl;
+        const fullServerUrl = `${baseUrl}/api/${appliedApiVersion}/`;
+        swaggerSystemRef.current.specActions.updateJsonSpec({
+          ...spec.toJS(),
+          servers: [{ url: fullServerUrl, description: 'Configured Recon Server' }]
+        });
+      }
+    }
+  }, [appliedServerUrl, appliedApiVersion]);
+
+  const handleApply = () => {
+    setAppliedServerUrl(serverUrl);
+    setAppliedApiVersion(apiVersion);
+  };
+
+  return (
+    <div className={styles.swaggerWrapper}>
+      <div className={styles.serverConfig}>
+        <label htmlFor="recon-server-url" className={styles.serverLabel}>
+          Recon Server URL:
+        </label>
+        <input
+          id="recon-server-url"
+          type="text"
+          value={serverUrl}
+          onChange={(e) => setServerUrl(e.target.value)}
+          placeholder="http://localhost:9888"
+          className={styles.serverInput}
+        />
+        <label htmlFor="recon-api-version" className={styles.serverLabel}>
+          API Version:
+        </label>
+        <input
+          id="recon-api-version"
+          type="text"
+          value={apiVersion}
+          onChange={(e) => setApiVersion(e.target.value)}
+          placeholder="v1"
+          className={styles.versionInput}
+        />
+        <button
+          onClick={handleApply}
+          className={styles.applyButton}
+          type="button"
+        >
+          Apply
+        </button>
+        <span className={styles.serverHint}>
+          (Default for Docker quick start. Change server/version and click Apply.)
+        </span>
+      </div>
+      <SwaggerUI 
+        url={specUrl}
+        docExpansion="list"
+        defaultModelsExpandDepth={1}
+        defaultModelExpandDepth={1}
+        onComplete={(system) => {
+          // Store the system reference for later updates
+          swaggerSystemRef.current = system;
+          // Set initial server URL with API version
+          const spec = system.getState().getIn(['spec', 'json']);
+          if (spec) {
+            const baseUrl = appliedServerUrl.endsWith('/') ? appliedServerUrl.slice(0, -1) : appliedServerUrl;
+            const fullServerUrl = `${baseUrl}/api/${appliedApiVersion}/`;
+            system.specActions.updateJsonSpec({
+              ...spec.toJS(),
+              servers: [{ url: fullServerUrl, description: 'Configured Recon Server' }]
+            });
+          }
+        }}
+      />
+    </div>
+  );
+}