Provides end user documentation via GitHub pages

Generating on-the-fly using Swagger UI and the version of the api spec in the main branch of the repository. We will want to consider options to provide more control of which version of the API spec we use in case we merge changes into main prior to launching the changes into production but we currently need to get this solution into production as our current solution was deleted by the vendor with no notice.
MITLibraries · Feb 23, 2022 · 1bb91c8 · 1bb91c8
1 parent e3b4cdc
commit 1bb91c8
Show file tree

Hide file tree

Showing 5 changed files with 17 additions and 109 deletions.
diff --git a/README.md b/README.md
@@ -44,11 +44,8 @@ particular order so as not to break production services.
 
 ### Automatic generation from openapi specification
 
-- Sign into stoplight.io with an account that has access to the MIT Libraries organization
-- copy the source of `openapi.json` file from this repository to the code tab in our [stoplight model](https://next.stoplight.io/mit-libraries/timdex/version%2F1.0/openapi.oas3.yml)
-- In [Stoplight's Publish](https://next.stoplight.io/mit-libraries/timdex/version%2F1.0/timdex.hub.yml?view=/&show=publish&domain=mitlibraries-timdex.docs.stoplight.io) section, Uncheck "set live" and then click "Build"
-- Once docs are built, check they are sane with the preview feature then click "set live"
-
+We are using Swagger UI to automatically generate documentation from the `openapi.json` file in GitHub Pages. The HTML
+file is in `docs/index.html` and the `openapi.json` file always pulls from the `main` branch.
 ## Required Environment Variables (all ENVs)
 
 - `EMAIL_FROM`: email address to send message from, including the registration

diff --git a/app/views/static/index.html.erb b/app/views/static/index.html.erb
@@ -7,9 +7,9 @@
 
       <p>TIMDEX is a free discovery API into collections at MIT Libraries.</p>
 
-      <p>This initial release provides discovery of records in MIT Libraries Barton catalog. We intend to expand the scope of collections discoverable via this API.</p>
+      <p>This release provides discovery of records in MIT Libraries catalog and ArchivesSpace. We intend to expand the scope of collections discoverable via this API.</p>
 
-      <p>Interactive <a href="https://mitlibraries-timdex.docs.stoplight.io">end user documentation</a> is available for the REST API with selectable language code samples and live API calls against real production data.</p>
+      <p>Interactive <a href="https://mitlibraries.github.io/timdex/">end user documentation</a> is available for the REST API with Curl examples and live API calls against real production data.</p>
 
       <p>There is also a <a href="https://graphql.org">GraphQL</a> endpoint by posting to <%= link_to(graphql_url) %> as well as an <a href="/playground">interactive GraphQL playground.</a> It's neat, check it out!.</p>
 

diff --git a/docs/index.html b/docs/index.html
@@ -1,61 +1,22 @@
-<!-- HTML for static distribution bundle build -->
 <!DOCTYPE html>
 <html lang="en">
   <head>
-    <meta charset="UTF-8">
-    <title>TIMDEX API Documentationd</title>
-    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3.19.5/swagger-ui.css" >
-    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
-    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
-    <style>
-      html
-      {
-        box-sizing: border-box;
-        overflow: -moz-scrollbars-vertical;
-        overflow-y: scroll;
-      }
-
-      *,
-      *:before,
-      *:after
-      {
-        box-sizing: inherit;
-      }
-
-      body
-      {
-        margin:0;
-        background: #fafafa;
-      }
-    </style>
-
-    <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="MIT Libraries TIMDEX API Documentation" />
+    <title>MIT Libraries TIMDEX API Documentation</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.2/swagger-ui.css" />
   </head>
-
   <body>
     <div id="swagger-ui"></div>
-
+    <script src="https://unpkg.com/swagger-ui-dist@4.5.2/swagger-ui-bundle.js" crossorigin></script>
     <script>
-
-    window.onload = function() {
-      // Begin Swagger UI call region
-      const ui = SwaggerUIBundle({
-        url: "../openapi.json",
-        dom_id: '#swagger-ui',
-        deepLinking: true,
-        presets: [
-          SwaggerUIBundle.presets.apis,
-          // SwaggerUIStandalonePreset
-        ],
-        plugins: [
-          SwaggerUIBundle.plugins.DownloadUrl
-        ],
-        // layout: "StandaloneLayout"
-      })
-      // End Swagger UI call region
-
-      window.ui = ui
-    }
-  </script>
+      window.onload = () => {
+        window.ui = SwaggerUIBundle({
+          url: "https://raw.githubusercontent.com/MITLibraries/timdex/main/openapi.json",
+          dom_id: "#swagger-ui",
+        });
+      };
+    </script>
   </body>
 </html>
diff --git a/docs/rapidoc.html b/docs/rapidoc.html
diff --git a/docs/redoc.html b/docs/redoc.html