chore: refactor api docs (#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 <liboliqi@gmail.com>

* Update api/doc/thor.yaml

Co-authored-by: libotony <liboliqi@gmail.com>

* Update api/doc/thor.yaml

Co-authored-by: libotony <liboliqi@gmail.com>

* Update api/doc/thor.yaml

Co-authored-by: libotony <liboliqi@gmail.com>

* Update api/doc/thor.yaml

Co-authored-by: libotony <liboliqi@gmail.com>

* 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 <liboliqi@gmail.com>

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

Co-authored-by: libotony <liboliqi@gmail.com>

* chore: update PR for comments

* chore: update readme

* fix: remove javascript type

---------

Co-authored-by: libotony <liboliqi@gmail.com>

.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/swagger-ui-dist@5.11.2/swagger-ui.css > swagger-ui/swagger-ui.css
+curl https://unpkg.com/swagger-ui-dist@5.11.2/swagger-ui-bundle.js > swagger-ui/swagger-ui-bundle.js
+curl https://unpkg.com/swagger-ui-dist@5.11.2/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/elements@8.0.3/styles.min.css > stoplight-ui/styles.min.css
+curl https://unpkg.com/@stoplight/elements@8.0.3/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>