add openapi3 doc

client-react-carbon/package.json

@@ -21,6 +21,7 @@
     "react-router-dom": "^5.2.0",
     "react-router-hash-link": "^2.4.3",
     "react-scripts": "4.0.3",
+    "swagger-ui": "4.13.0",
     "web-vitals": "^1.0.1"
   },
   "scripts": {

client-react-carbon/src/App.js

@@ -3,7 +3,7 @@ import { Route, Switch } from "react-router-dom";
 import "carbon-components/css/carbon-components.min.css";
 import "./App.css";
 import { Loading } from "carbon-components-react";
-import { HqPageAll, HqPageTag, HqPageDoc } from "./pages";
+import { HqPageAll, HqPageTag, HqPageSwagger } from "./pages";
 import { HqFooter, HqHeader, HqTagList } from "./components";
 import { useInterval } from "./utils/useInterval";
 import Headroom from "react-headroom";
@@ -66,7 +66,7 @@ function App() {
           <HqPageTag data={data} />
         </Route>
         <Route path="/doc">
-          <HqPageDoc />
+          <HqPageSwagger />
         </Route>
       </Switch>
       <HqFooter

client-react-carbon/src/components/SwaggerUIComp.js

@@ -0,0 +1,19 @@
+import React, { useEffect } from "react";
+import SwaggerUI from "swagger-ui";
+import swaggerData from "../utils/swaggerData";
+import 'swagger-ui/dist/swagger-ui.css';
+
+const SwaggerUIComp = () => {
+
+  useEffect(() => {
+    SwaggerUI({
+      spec: swaggerData,
+      dom_id: '#swagger'
+    });
+  }, []);
+
+  return <div id="swagger"></div>
+
+};
+
+export default SwaggerUIComp;

client-react-carbon/src/components/index.js

@@ -5,4 +5,5 @@ export { default as HqHeader } from "./HqHeader";
 export { default as HqTagList } from "./HqTagList";
 export { default as HqEntryOpen } from "./HqEntryOpen";
 export { default as HqEntryClosed } from "./HqEntryClosed";
-export { default as HqFooter } from "./HqFooter";
+export { default as HqFooter } from "./HqFooter";
+export { default as SwaggerUIComp } from "./SwaggerUIComp";

client-react-carbon/src/pages/HqPageSwagger.css

@@ -0,0 +1,50 @@
+h3 {
+  margin-top: 2.0rem;
+  margin-bottom: 0.8rem;
+  padding-left: 0;
+  border-left: none;
+  color: #3b4151;
+  font-size: 1.75rem;
+  margin: 0 0 5px;
+  box-sizing: border-box;
+}
+.swagger-ui .info .title {
+  color: #161616;
+  font-family: "IBM Plex Sans";
+  font-size: 2rem;
+  font-weight: 400;
+  line-height: 1.25;
+  letter-spacing: 0;
+}
+.swagger-ui .wrapper {
+  box-sizing: border-box;
+  margin: 0;
+  max-width: 1460px;
+  padding: 0;
+  width: 100%;
+}
+.doc-title {
+  display: flex;
+  flex-flow: row nowrap;
+  justify-content: left;
+  align-items: baseline;
+}
+.doc-section-legend ul {
+  margin-top: 2.0rem;
+  margin-left: 10px;
+}
+.doc-tag {
+  margin-bottom: 2.0rem;
+  display: flex;
+  flex-flow: column nowrap;
+  justify-content: flex-start;
+  align-content: flex-start;
+}
+.doc-tag-item {
+  display: flex;
+  flex-flow: row wrap;
+}
+.doc-tag-item > div {
+  margin-left: -8px;
+  padding: 0 8px 0 8px;
+}

client-react-carbon/src/pages/HqPageSwagger.js

@@ -0,0 +1,65 @@
+import React from "react";
+import { Grid, Row, Column, Content, Tag } from "carbon-components-react";
+import { SwaggerUIComp } from "../components";
+import "./HqPageSwagger.css";
+
+
+const HqPageSwagger = () => {
+
+  const colors = [
+    {
+      color: "red",
+      name: "has-blocker",
+      desc: "Red contains a blocker. Supersedes active.",
+    },
+    {
+      color: "blue",
+      name: "has-active",
+      desc: "Blue contains open active items (in progress or milestone ♦). Supersedes pending.",
+    },
+    {
+      color: "teal",
+      name: "has-pending",
+      desc: "Teal contains open pending items (backlog, none in progress). Supersedes green.",
+    },
+    {
+      color: "green",
+      name: "has-closed",
+      desc: "Green contains closed items (nothing currently open).",
+    },
+  ];
+
+  return (
+    <Grid>
+      <Row>
+        <Column>
+        <Content className="doc-page-content">
+            <h1>Help</h1>
+            <ul>
+              <li>To scroll through the tag list when viewed from a desktop browser,
+                use the arrow buttons or hold down Shift while scrolling the mouse wheel.</li>
+            </ul>
+            <h2 id="doc-legend">Tag color legend</h2>
+            <div className="doc-section-legend">
+              <ul>
+                {colors.map((c) => (
+                  <li className="doc-tag" key={c.name}>
+                    <div className="doc-tag-item">
+                      <Tag type={c.color} id={c.name} title={c.name}>
+                        <span>{c.name.replace('-', ' ')}</span>
+                      </Tag>
+                    </div>
+                    <div className="doc-tag-description">{c.desc}</div>
+                  </li>
+                ))}
+              </ul>
+            </div>
+            <SwaggerUIComp/>
+          </Content>
+        </Column>
+      </Row>
+    </Grid>
+  );
+};
+
+export default HqPageSwagger;

client-react-carbon/src/pages/index.js

@@ -1,3 +1,4 @@
 export { default as HqPageAll } from "./HqPageAll";
 export { default as HqPageTag } from "./HqPageTag";
 export { default as HqPageDoc } from "./HqPageDoc";
+export { default as HqPageSwagger } from "./HqPageSwagger";

client-react-carbon/src/utils/README.md

@@ -0,0 +1,16 @@
+# Creating the swagger doc
+
+Some utilities in this directory are for manual use to create the Swagger doc.
+The `serverApi.yml` file is the source of truth for the Swagger doc.
+
+To create examples to be added to `serverApi.yml`:
+
+1. Query the server API and copy the raw JSON (or HTML for `/ejs` endpoints) data.
+2. Paste that data as the value for `origdata` in the `stringify.js` file.
+3. Run `node stringify.js` to product the `strung.json file`.
+4. Edit `strung.json` content as needed and copy'n'paste the results into `serverApi.yml`
+   where needed.
+
+When finished editing `serverApi.yml`, to prepare the content for inclusion into the app,
+run `python3 y2j.py`, which turns the YML into JSON and rewrites the `swaggerData.js` file,
+That file is used in the `SwaggerUIComp.js` component.