API: Separate core and plugin docs (#1345)

* API: Separate core and plugin docs Closes #1343. * Add gitkeep file * Cross-reference API v1 docs * Add external/plugin docs reference for core API docs
btcpayserver · Nov 2, 2023 · ce07676 · ce07676
1 parent 39688c3
commit ce07676
Show file tree

Hide file tree

Showing 7 changed files with 110 additions and 39 deletions.
diff --git a/.gitignore b/.gitignore
@@ -25,6 +25,7 @@
 /docs/img/btcpayexposecloudflare*
 /docs/img/cloudflare*
 /docs/img/Cloudflare*
+/swagger/plugins/**
 
 # Constructed docs
 /docs/Development/LocalDevelopment.md

diff --git a/docs/.vuepress/public/API/Greenfield/Plugins/index.html b/docs/.vuepress/public/API/Greenfield/Plugins/index.html
@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>BTCPay Greenfield API (Plugins)</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    <!--
+    ReDoc doesn't change outer page styles
+    -->
+    <style>
+        body {
+            margin: 0;
+            padding: 0;
+        }
+    </style>
+</head>
+<body>
+    <redoc spec-url="./swagger.json"></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]/bundles/redoc.standalone.js" integrity="sha384-RC31+q3tyqdcilXYaU++ii/FAByqeZ+sjKUHMJ8hMzIY5k4kzNqi4Ett88EZ/4lq" crossorigin="anonymous"></script>
+</body>
+</html>
diff --git a/docs/.vuepress/public/API/Greenfield/v1/index.html b/docs/.vuepress/public/API/Greenfield/v1/index.html
@@ -6,7 +6,6 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
-
     <!--
     ReDoc doesn't change outer page styles
     -->

diff --git a/setup-deps.sh b/setup-deps.sh
@@ -55,9 +55,6 @@ for file in "$DOCS_DIR"/BTCPayServer/*.md; do
   update_external "$file" https://github.com/btcpayserver/btcpayserver "$DOCS_DIR"/BTCPayServer/
 done
 
-# Checkout latest release tag, so that we do not publish docs for unreleased APIs yet.
-git checkout $(git tag --sort -version:refname | awk 'match($0, /^v[0-9]+\.[0-9]+\.[0-9]+$/)' | head -n 1)
-
 # NBXplorer
 
 echo "Setup dependency: NBXplorer"
@@ -208,7 +205,7 @@ for file in "$DOCS_DIR"/LNbank/*.md; do
   update_external "$file" https://github.com/dennisreimann/btcpayserver-plugin-lnbank "$DOCS_DIR"/LNbank/
 done
 
-cp -r BTCPayServer.Plugins.LNbank/Resources/swagger/* "$BTCPAYSERVER_DIR/BTCPayServer/wwwroot/swagger/"
+cp -r BTCPayServer.Plugins.LNbank/Resources/swagger/* "$BASE_DIR/swagger/plugins"
 
 # PodServer
 
@@ -248,31 +245,6 @@ for file in "$DOCS_DIR"/LNDhubAPI/*.md; do
   update_external "$file" https://github.com/dennisreimann/btcpayserver-plugin-lndhub-api "$DOCS_DIR"/LNDhubAPI/
 done
 
-# Swagger
-
-cd "$BTCPAYSERVER_DIR"
-
-if command -v jq >/dev/null 2>&1; then
-  swagger_file="$PUBLIC_DIR/API/Greenfield/v1/swagger.json"
-  jq -rs 'def deepmerge(a;b):
-  reduce b[] as $item (a;
-    reduce ($item | keys_unsorted[]) as $key (.;
-      $item[$key] as $val | ($val | type) as $type | .[$key] = if ($type == "object") then
-        deepmerge({}; [if .[$key] == null then {} else .[$key] end, $val])
-      elif ($type == "array") then
-        (.[$key] + $val | unique)
-      else
-        $val
-      end)
-    );
-  deepmerge({}; .)' BTCPayServer/wwwroot/swagger/v1/*.json > $swagger_file
-
-  # report but don't stop on error
-  set +e
-  REDOCLY_TELEMETRY=off npx @redocly/cli lint $swagger_file
-  set -e
-fi
-
 # Trocador
 
 echo "Setup dependency: Trocador"
@@ -303,30 +275,82 @@ if [ ! -d "$KUKKS_DIR" ]; then
   git clone --depth 1 https://github.com/Kukks/BTCPayServerPlugins.git "$KUKKS_DIR"
 fi
 
-cd "$KUKKS_DIR"
-
-cd "Plugins/BTCPayServer.Plugins.Wabisabi"
+cd "$KUKKS_DIR/Plugins/BTCPayServer.Plugins.Wabisabi"
 
 cp -r readme.md docs/* "$DOCS_DIR/Wabisabi"
 sed -ie 's$docs/$./$g' "$DOCS_DIR/Wabisabi/readme.md"
 for file in "$DOCS_DIR"/Wabisabi/*.md; do
   update_external "$file" https://github.com/Kukks/BTCPayServerPlugins/tree/master/Plugins/BTCPayServer.Plugins.Wabisabi "$DOCS_DIR"/Wabisabi/
 done
 
-cd -
-
-cd "Plugins/BTCPayServer.Plugins.TicketTailor"
+cd "$KUKKS_DIR/Plugins/BTCPayServer.Plugins.TicketTailor"
 
 cp -r README.md "$DOCS_DIR/TicketTailor"
 for file in "$DOCS_DIR"/TicketTailor/*.md; do
   update_external "$file" https://github.com/Kukks/BTCPayServerPlugins/tree/master/Plugins/BTCPayServer.Plugins.TicketTailor "$DOCS_DIR"/TicketTailor/
 done
 
-cd -
-
-cd "Plugins/BTCPayServer.Plugins.NIP05"
+cd "$KUKKS_DIR/Plugins/BTCPayServer.Plugins.NIP05"
 
 cp -r readme.md "$DOCS_DIR/Nostr"
 for file in "$DOCS_DIR"/Nostr/*.md; do
   update_external "$file" https://github.com/Kukks/BTCPayServerPlugins/tree/master/Plugins/BTCPayServer.Plugins.NIP05 "$DOCS_DIR"/Nostr/
 done
+
+# Swagger
+
+# BTCPay Swagger: Checkout latest release tag, so that we do not publish docs for unreleased APIs yet
+
+cd "$BTCPAYSERVER_DIR"
+
+git checkout $(git tag --sort -version:refname | awk 'match($0, /^v[0-9]+\.[0-9]+\.[0-9]+$/)' | head -n 1)
+
+# Swagger
+if command -v jq >/dev/null 2>&1; then
+  swagger_file="$PUBLIC_DIR/API/Greenfield/v1/swagger.json"
+  jq -rs 'def deepmerge(a;b):
+  reduce b[] as $item (a;
+    reduce ($item | keys_unsorted[]) as $key (.;
+      $item[$key] as $val | ($val | type) as $type | .[$key] = if ($type == "object") then
+        deepmerge({}; [if .[$key] == null then {} else .[$key] end, $val])
+      elif ($type == "array") then
+        (.[$key] + $val | unique)
+      else
+        $val
+      end)
+    );
+  deepmerge({}; .)' BTCPayServer/wwwroot/swagger/v1/*.json $BASE_DIR/swagger/btcpay.json > $swagger_file
+
+  # report but don't stop on error
+  set +e
+  REDOCLY_TELEMETRY=off npx @redocly/cli lint $swagger_file
+  set -e
+fi
+
+# We need the base file to be able to generate the swagger for the plugins
+cp BTCPayServer/wwwroot/swagger/v1/swagger.template.json $BASE_DIR/swagger/plugins/btcpay.json
+
+# Plugin Swagger
+
+cd $BASE_DIR
+
+if command -v jq >/dev/null 2>&1; then
+  swagger_file="$PUBLIC_DIR/API/Greenfield/Plugins/swagger.json"
+  jq -rs 'def deepmerge(a;b):
+  reduce b[] as $item (a;
+    reduce ($item | keys_unsorted[]) as $key (.;
+      $item[$key] as $val | ($val | type) as $type | .[$key] = if ($type == "object") then
+        deepmerge({}; [if .[$key] == null then {} else .[$key] end, $val])
+      elif ($type == "array") then
+        (.[$key] + $val | unique)
+      else
+        $val
+      end)
+    );
+  deepmerge({}; .)' swagger/plugins/btcpay.json swagger/plugins.json swagger/plugins/**/*.json > $swagger_file
+
+  # report but don't stop on error
+  set +e
+  REDOCLY_TELEMETRY=off npx @redocly/cli lint $swagger_file --skip-rule=no-unused-components
+  set -e
+fi
diff --git a/swagger/btcpay.json b/swagger/btcpay.json
@@ -0,0 +1,6 @@
+{
+  "externalDocs": {
+    "description": "BTCPay Greenfield Plugins API",
+    "url": "https://docs.btcpayserver.org/API/Greenfield/Plugins/"
+  }
+}
diff --git a/swagger/plugins.json b/swagger/plugins.json
@@ -0,0 +1,18 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "BTCPay Server Greenfield Plugin API",
+    "version": "Plugins",
+    "description": "Plugin APIs for BTCPay Server"
+  },
+  "servers": [
+    {
+      "url": "/",
+      "description": "BTCPay Server Greenfield Plugin API"
+    }
+  ],
+  "externalDocs": {
+    "description": "BTCPay Greenfield API (v1)",
+    "url": "https://docs.btcpayserver.org/API/Greenfield/v1/"
+  }
+}
diff --git a/swagger/plugins/.gitkeep b/swagger/plugins/.gitkeep