fix: add webhook documentation to generated docs (#523)

This PR adds documentation for the various services' webhooks - Update generated mdbook so that the external REST API and the webhook API each have their own page, instead of all being inline in the main service page - Generate HTML UI for the webhooks
ProjectLibertyLabs · Sep 23, 2024 · 30737f7 · 30737f7
1 parent 1adb76d
commit 30737f7
Show file tree

Hide file tree

Showing 22 changed files with 2,765 additions and 10,680 deletions.
diff --git a/docs/account/index.html b/docs/account/index.html
diff --git a/docs/account/webhooks.html b/docs/account/webhooks.html
diff --git a/docs/content-publishing/index.html b/docs/content-publishing/index.html
diff --git a/docs/content-watcher/index.html b/docs/content-watcher/index.html
diff --git a/docs/content-watcher/webhooks.html b/docs/content-watcher/webhooks.html
diff --git a/docs/graph/index.html b/docs/graph/index.html
diff --git a/docs/graph/webhooks.html b/docs/graph/webhooks.html
diff --git a/docs/src/Build/AccountService.md → ...rc/Build/AccountService/AccountService.md b/docs/src/Build/AccountService.md → ...rc/Build/AccountService/AccountService.md
@@ -5,8 +5,8 @@ It includes endpoints for managing user authentication, account details, delegat
 
 ## API Reference
 
-[Open Direct API Reference Page](https://projectlibertylabs.github.io/gateway/account)
-{{#swagger-embed ../openapi-specs/account.openapi.json}}
+- [REST API](./Api.md) (<a target="_blank" href="https://projectlibertylabs.github.io/gateway/account">Full docs</a>)
+- [Webhooks](./Webhooks.md) (<a target="_blank" href="https://projectlibertylabs.github.io/gateway/account/webhooks.html">Full docs</a>)
 
 ## Configuration
 

diff --git a/docs/src/Build/AccountService/Api.md b/docs/src/Build/AccountService/Api.md
@@ -0,0 +1,6 @@
+# Account Service
+
+## API Reference
+
+[Open Direct API Reference Page](https://projectlibertylabs.github.io/gateway/account)
+{{#swagger-embed ../openapi-specs/account.openapi.json}}
diff --git a/docs/src/Build/AccountService/Webhooks.md b/docs/src/Build/AccountService/Webhooks.md
@@ -0,0 +1,6 @@
+# Account Service
+
+## Webhooks API Reference
+
+[Open Direct API Reference Page](https://projectlibertylabs.github.io/gateway/account/webhooks.html)
+{{#swagger-embed ../openapi-specs/account-webhooks.openapi.json}}
diff --git a/docs/src/Build/ContentPublishing/Api.md b/docs/src/Build/ContentPublishing/Api.md
@@ -0,0 +1,6 @@
+# Content Watcher Service
+
+## API Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/content-publishing)
+{{#swagger-embed ../openapi-specs/content-publishing.openapi.json}}
diff --git a/docs/src/Build/ContentPublishing.md → ...ld/ContentPublishing/ContentPublishing.md b/docs/src/Build/ContentPublishing.md → ...ld/ContentPublishing/ContentPublishing.md
@@ -4,8 +4,7 @@ The Content Publishing Service allows users to create, post, and manage content
 
 ## API Reference
 
-[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/content-publishing)
-{{#swagger-embed ../openapi-specs/content-publishing.openapi.json}}
+- [REST API](./Api.md) (<a target="_blank" href="https://projectlibertylabs.github.io/gateway/content-publishing">Full docs</a>)
 
 ## Configuration
 

diff --git a/docs/src/Build/ContentWatcher/Api.md b/docs/src/Build/ContentWatcher/Api.md
@@ -0,0 +1,6 @@
+# Content Watcher Service
+
+## API Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/content-watcher)
+{{#swagger-embed ../openapi-specs/content-watcher.openapi.json}}
diff --git a/docs/src/Build/ContentWatcher.md → ...rc/Build/ContentWatcher/ContentWatcher.md b/docs/src/Build/ContentWatcher.md → ...rc/Build/ContentWatcher/ContentWatcher.md
@@ -4,8 +4,8 @@ The Content Watcher Service monitors and retrieves the latest feed state, includ
 
 ## API Reference
 
-[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/content-watcher)
-{{#swagger-embed ../openapi-specs/content-watcher.openapi.json}}
+- [REST API](./Api.md) (<a target="_blank" href="https://projectlibertylabs.github.io/gateway/content-watcher">Full docs</a>)
+- [Webhooks](./Webhooks.md) (<a target="_blank" href="https://projectlibertylabs.github.io/gateway/content-watcher/webhooks.html">Full docs</a>)
 
 
 ## Configuration

diff --git a/docs/src/Build/ContentWatcher/Webhooks.md b/docs/src/Build/ContentWatcher/Webhooks.md
@@ -0,0 +1,6 @@
+# Content Watcher Service
+
+## Webhooks Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/content-watcher/webhooks.html)
+{{#swagger-embed ../openapi-specs/content-announcement.openapi.json}}
diff --git a/docs/src/Build/GraphService/Api.md b/docs/src/Build/GraphService/Api.md
@@ -0,0 +1,6 @@
+# Graph Service
+
+## API Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/graph)
+{{#swagger-embed ../openapi-specs/graph.openapi.json}}
diff --git a/docs/src/Build/GraphService.md → docs/src/Build/GraphService/GraphService.md b/docs/src/Build/GraphService.md → docs/src/Build/GraphService/GraphService.md
@@ -4,8 +4,8 @@ The Graph Service manages the social graphs, including follow/unfollow actions,
 
 ## API Reference
 
-[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/graph)
-{{#swagger-embed ../openapi-specs/graph.openapi.json}}
+- [REST API](./Api.md) (<a target="_blank" href="https://projectlibertylabs.github.io/gateway/graph">Full docs</a>)
+- [Webhooks](./Webhooks.md) (<a target="_blank" href="https://projectlibertylabs.github.io/gateway/graph/webhooks.html">Full docs</a>)
 
 
 ## Configuration

diff --git a/docs/src/Build/GraphService/Webhooks.md b/docs/src/Build/GraphService/Webhooks.md
@@ -0,0 +1,6 @@
+# Graph Service
+
+## Webhooks Reference
+
+[Open Full API Reference Page](https://projectlibertylabs.github.io/gateway/graph/webhooks.html)
+{{#swagger-embed ../openapi-specs/graph-webhooks.openapi.yaml}}
diff --git a/docs/src/Build/README.md b/docs/src/Build/README.md
@@ -1,10 +1,10 @@
 # Services
 
 <div class="button-links">
-  <a href="./AccountService.html">Account Service</a>
-  <a href="./ContentPublisher.html">Content PublisherService</a>
-  <a href="./GraphService.html">Graph Service</a>
-  <a href="./ContentWatcher.html">Content WatcherService</a>
+  <a href="./AccountService/AccountService.html">Account Service</a>
+  <a href="./ContentPublishing.html">Content PublisherService</a>
+  <a href="./GraphService/GraphService.html">Graph Service</a>
+  <a href="./ContentWatcher/ContentWatcher.html">Content WatcherService</a>
 </div>
 
 {{#svg-embed ./src/TopLevel.svg Gateway Application Microservice Diagram}}
@@ -19,7 +19,7 @@ Accounts are defined as an `msaId` (64-bit identifier) and can contain additiona
 - User Handle creation and retrieval
 - User key retrieval and management
 
-See [Account Service Details & API Reference](./AccountService)
+See [Account Service Details & API Reference](./AccountService/README)
 
 ## Graph Service
 

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -11,10 +11,17 @@
   - [Gateway Architecture](./Fundamentals/Architecture.md)
   - [Migrating from Web2 to Web3](./Fundamentals/Migrating.md)
 - [Build](./Build/README.md)
-  - [Account Service](./Build/AccountService.md)
-  - [Content Publishing Service](./Build/ContentPublishing.md)
-  - [Content Watcher Service](./Build/ContentWatcher.md)
-  - [Graph Service](./Build/GraphService.md)
+  - [Account Service](./Build/AccountService/AccountService.md)
+    - [REST API](./Build/AccountService/Api.md)
+    - [Webhooks API](./Build/AccountService/Webhooks.md)
+  - [Content Publishing Service](./Build/ContentPublishing/ContentPublishing.md)
+    - [REST API](./Build/ContentPublishing/Api.md)
+  - [Content Watcher Service](./Build/ContentWatcher/ContentWatcher.md)
+    - [REST API](./Build/ContentWatcher/Api.md)
+    - [Webhooks API](./Build/ContentWatcher/Webhooks.md)
+  - [Graph Service](./Build/GraphService/GraphService.md)
+    - [REST API](./Build/GraphService/Api.md)
+    - [Webhooks API](./Build/GraphService/Webhooks.md)
 - [Run](./Run/README.md)
   - [Deployment](./Run/Deployment.md)
   - [Security](./Run/Security.md)

diff --git a/openapi-specs/graph-webhooks.openapi.yaml b/openapi-specs/graph-webhooks.openapi.yaml
@@ -8,7 +8,7 @@ openapi: 3.1.0
 info:
   title: Graph Service Webhooks API
   version: 1.0.0
-webhooks:
+paths:
   graph-update:
     post:
       summary: Announce a graph update

diff --git a/package.json b/package.json
@@ -66,10 +66,13 @@
     "generate:types:graph": "npx openapi-client-axios-typegen openapi-specs/graph-webhooks.openapi.yaml > libs/types/src/graph-webhook/webhook-types.d.ts ; prettier --write libs/types/src/graph-webhook/webhook-types.d.ts",
     "generate:types:content-watcher": "npx @hey-api/openapi-ts -i openapi-specs/content-announcement.openapi.json -o libs/types/src/content-announcement ; prettier --write libs/types/src/content-announcement",
     "generate:types": "npm run generate:types:account ; npm run generate:types:graph ; npm run generate:types:content-watcher",
+    "pregenerate:swagger-ui:account": "npx --yes @redocly/cli build-docs openapi-specs/account-webhooks.openapi.yaml --output=./docs/account/webhooks.html",
     "generate:swagger-ui:account": "npx --yes @redocly/cli build-docs openapi-specs/account.openapi.json --output=./docs/account/index.html",
     "generate:swagger-ui:content-publishing": "npx --yes @redocly/cli build-docs openapi-specs/content-publishing.openapi.json --output=./docs/content-publishing/index.html",
+    "pregenerate:swagger-ui:content-watcher": "npx --yes @redocly/cli build-docs openapi-specs/content-announcement.openapi.json --output=./docs/content-watcher/webhooks.html",
     "generate:swagger-ui:content-watcher": "npx --yes @redocly/cli build-docs openapi-specs/content-watcher.openapi.json --output=./docs/content-watcher/index.html",
     "generate:swagger-ui:graph": "npx --yes @redocly/cli build-docs openapi-specs/graph.openapi.json --output=./docs/graph/index.html",
+    "pregenerate:swagger-ui:graph": "npx --yes @redocly/cli build-docs openapi-specs/graph-webhooks.openapi.yaml --output=./docs/graph/webhooks.html",
     "generate:swagger-ui": "npm run generate:swagger-ui:account ; npm run generate:swagger-ui:content-publishing ; npm run generate:swagger-ui:content-watcher ; npm run generate:swagger-ui:graph",
     "test:account": "dotenvx run -f env-files/account.template.env -- jest 'account*'",
     "test:content-publishing": "dotenvx run -f env-files/content-publishing.template.env -- jest 'content-publishing*'",