chore: refactor api docs (vechain#628)

* chore: refactor api docs

* chore: remove a test change

* chore: remove a test change

* chore: update docs to show nullable/optional fields

* chore: minor updates for naming

* chore: revert tag change

* remove code cove and fix thor url

* remove .DS_store

* remove .DS_store

* remove test.cov

* remove .DS_store

* updates for PR comments

* update API docs image

* updates for PR comments

* updates for PR comments

* update thor.yaml

* update thor.yaml

* update required and nullable fields

* revert .gitignore

* remove TODO

* remove 'nullable' descriptions

* fix: update thor.yaml

* chore: update thor.yaml

* fix allOf errors

* chore: update thor.yaml

* fix: thor.yaml typo

* fix: thor.yaml regex

* chore: update thor.yaml

* fix: update lint error

* chore: update thor.yaml to include 'best' in query

* Update api/doc/thor.yaml

Co-authored-by: libotony <[email protected]>

* Update api/doc/thor.yaml

Co-authored-by: libotony <[email protected]>

* Update api/doc/thor.yaml

Co-authored-by: libotony <[email protected]>

* Update api/doc/thor.yaml

Co-authored-by: libotony <[email protected]>

* Update api/doc/thor.yaml

Co-authored-by: libotony <[email protected]>

* fix: yaml formatting error

* fix: duplicate 'required'

* feat: add swagger and install instructions

* fix: schema titles

* chore: update block response name

* Update api/doc/swagger-ui/window-observer.js

Co-authored-by: libotony <[email protected]>

* Update api/doc/api-docs/window-observer.js

Co-authored-by: libotony <[email protected]>

* chore: update PR for comments

* chore: update readme

* fix: remove javascript type

---------

Co-authored-by: libotony <[email protected]>

.github/workflows/close-stale-issues.yaml

@@ -7,6 +7,8 @@ on:
 jobs:
   stale:
     runs-on: ubuntu-latest
+    # only run this action on `vechain/thor` repository
+    if: github.repository == 'vechain/thor'
 
     permissions:
       contents: write

.github/workflows/qodana-scan.yaml

@@ -7,6 +7,8 @@ on:
 
 jobs:
   scan_qodana:
+    # only run this action on `vechain/thor` repository
+    if: github.repository == 'vechain/thor'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code

README.md

@@ -191,7 +191,7 @@ volumes:
 
 ## API
 
-Once `thor` has started, the online *OpenAPI* doc can be accessed in your browser. e.g. [http://localhost:8669/](http://localhost:8669) by default.
+Once `thor` has started, the online *OpenAPI* documentation can be accessed in your browser. e.g. [http://localhost:8669/](http://localhost:8669) by default.
 
 [![Thorest](https://raw.githubusercontent.com/vechain/thor/master/thorest.png)](http://localhost:8669/)
 
@@ -201,6 +201,7 @@ A special shout out to following projects:
 
 * [Ethereum](https://github.com/ethereum)
 * [Swagger](https://github.com/swagger-api)
+* [Stoplight Elements](https://github.com/stoplightio/elements)
 
 ## Contributing
 

api/api.go

@@ -51,15 +51,15 @@ func New(
 
 	router := mux.NewRouter()
 
-	// to serve api doc and swagger-ui
+	// to serve api docs
 	router.PathPrefix("/doc").Handler(
 		http.StripPrefix("/doc/", http.FileServer(http.FS(doc.FS))),
 	)
 
-	// redirect swagger-ui
+	// redirect stoplight-ui
 	router.Path("/").HandlerFunc(
 		func(w http.ResponseWriter, req *http.Request) {
-			http.Redirect(w, req, "doc/swagger-ui/", http.StatusTemporaryRedirect)
+			http.Redirect(w, req, "doc/stoplight-ui/", http.StatusTemporaryRedirect)
 		})
 
 	accounts.New(repo, stater, callGasLimit, forkConfig).

api/doc/README.md

@@ -1 +1,19 @@
-swagger-ui from https://github.com/swagger-api/swagger-ui @v3.17.6
+## Swagger
+
+swagger-ui from https://github.com/swagger-api/swagger-ui @v5.11.2
+- Created [window-observer.js](swagger-ui/window-observer.js) to remove `Try it out` functionality for subscription endpoints
+
+```bash
+curl https://unpkg.com/[email protected]/swagger-ui.css > swagger-ui/swagger-ui.css
+curl https://unpkg.com/[email protected]/swagger-ui-bundle.js > swagger-ui/swagger-ui-bundle.js
+curl https://unpkg.com/[email protected]/swagger-ui-standalone-preset.js > swagger-ui/swagger-ui-standalone-preset.js
+```
+
+## Stoplight
+Spotlight UI from https://github.com/stoplightio/elements @v8.0.3
+- Created [window-observer.js](stoplight-ui/window-observer.js) to remove `Send API Request` functionality for subscription endpoints
+
+```bash
+curl https://unpkg.com/@stoplight/[email protected]/styles.min.css > stoplight-ui/styles.min.css
+curl https://unpkg.com/@stoplight/[email protected]/web-components.min.js > stoplight-ui/web-components.min.js
+```

api/doc/doc.go

@@ -11,7 +11,9 @@ import (
 	"gopkg.in/yaml.v2"
 )
 
-//go:embed swagger-ui thor.yaml
+// FS embeds the Open API specs and documentation.
+//
+//go:embed thor.yaml stoplight-ui swagger-ui icons
 var FS embed.FS
 var version string
 

api/doc/stoplight-ui/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport">
+    <title>Thor API</title>
+    <!-- Embed elements Elements via Web Component -->
+    <script src="./web-components.min.js"></script>
+    <script charset="UTF-8" src="./window-observer.js"> </script>
+    <link href="./styles.min.css" rel="stylesheet">
+    <link href="/doc/icons/favicon-32x32.png" rel="icon" sizes="32x32" type="image/png" />
+    <link href="/doc/icons/favicon-16x16.png" rel="icon" sizes="16x16" type="image/png" />
+    <link href="/doc/icons/favicon-96x96.png" rel="icon" sizes="96x96" type="image/png" />
+
+</head>
+<body>
+    <elements-api
+        apiDescriptionUrl="/doc/thor.yaml"
+        layout="sidebar"
+        logo="/doc/icons/favicon-96x96.png"
+        router="hash"
+    />
+</body>
+</html>

api/doc/stoplight-ui/window-observer.js

@@ -0,0 +1,14 @@
+/**
+ * This script is used to remove the "Send API request" button and the "Response" sections from WebSocket operations.
+ * @type {MutationObserver}
+ */
+const mutationObserver = new MutationObserver(() => {
+    if (window.location.hash?.includes("#/paths/subscriptions")) {
+        const element = document.querySelector('[data-testid="two-column-right"]');
+        if (element) {
+            element.remove();
+        }
+    }
+})
+
+mutationObserver.observe(document, {attributes: false, childList: true, characterData: false, subtree:true});

api/doc/swagger-ui/index.html

@@ -1,60 +1,30 @@
-<!-- HTML for static distribution bundle build -->
 <!DOCTYPE html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <title>Swagger UI</title>
-    <link rel="stylesheet" type="text/css" href="./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>
-  </head>
-
-  <body>
-    <div id="swagger-ui"></div>
-
-    <script src="./swagger-ui-bundle.js"> </script>
-    <script src="./swagger-ui-standalone-preset.js"> </script>
-    <script>
-    window.onload = function() {
-
-      // Build a system
-      const ui = SwaggerUIBundle({
-        url: "../thor.yaml",
-        dom_id: '#swagger-ui',
-        deepLinking: true,
-        presets: [
-          SwaggerUIBundle.presets.apis,
-          SwaggerUIStandalonePreset
-        ],
-        plugins: [
-          SwaggerUIBundle.plugins.DownloadUrl
-        ],
-        layout: "StandaloneLayout"
-      })
-
-      window.ui = ui
-    }
-  </script>
-  </body>
+<head>
+    <meta charset="utf-8" />
+    <title>Thor Swagger</title>
+    <link href="./swagger-ui.css" rel="stylesheet" />
+    <link href="/doc/icons/favicon-32x32.png" rel="icon" sizes="32x32" type="image/png" />
+    <link href="/doc/icons/favicon-16x16.png" rel="icon" sizes="16x16" type="image/png" />
+    <link href="/doc/icons/favicon-96x96.png" rel="icon" sizes="96x96" type="image/png" />
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script charset="UTF-8" src="./window-observer.js"> </script>
+<script crossorigin src="./swagger-ui-bundle.js"></script>
+<script crossorigin src="./swagger-ui-standalone-preset.js"></script>
+<script>
+    window.onload = () => {
+        window.ui = SwaggerUIBundle({
+            url: `${window.location.origin}/doc/thor.yaml`,
+            dom_id: '#swagger-ui',
+            presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset
+            ],
+            layout: "StandaloneLayout",
+        });
+    };
+</script>
+</body>
 </html>