From b3445305db362ff16172911de181c5fa6d5cae2b Mon Sep 17 00:00:00 2001 From: Dennis Reimann Date: Thu, 19 Oct 2023 12:11:54 +0200 Subject: [PATCH 1/4] API: Separate core and plugin docs Closes #1343. --- .gitignore | 1 + .../public/API/Greenfield/Plugins/index.html | 23 +++++ .../public/API/Greenfield/v1/index.html | 1 - setup-deps.sh | 89 +++++++++++-------- swagger/plugins.json | 14 +++ 5 files changed, 92 insertions(+), 36 deletions(-) create mode 100644 docs/.vuepress/public/API/Greenfield/Plugins/index.html create mode 100644 swagger/plugins.json diff --git a/.gitignore b/.gitignore index 31da683b42..0a845c48d7 100644 --- 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 new file mode 100644 index 0000000000..8075a8c93f --- /dev/null +++ b/docs/.vuepress/public/API/Greenfield/Plugins/index.html @@ -0,0 +1,23 @@ + + + + BTCPay Greenfield API (Plugins) + + + + + + + + + + + + diff --git a/docs/.vuepress/public/API/Greenfield/v1/index.html b/docs/.vuepress/public/API/Greenfield/v1/index.html index 7eaabea892..4e2c478ddb 100644 --- a/docs/.vuepress/public/API/Greenfield/v1/index.html +++ b/docs/.vuepress/public/API/Greenfield/v1/index.html @@ -6,7 +6,6 @@ - diff --git a/setup-deps.sh b/setup-deps.sh index 47ba7b1f27..c02b87b1fd 100755 --- a/setup-deps.sh +++ b/setup-deps.sh @@ -58,6 +58,31 @@ 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) +# 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 > $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 + # NBXplorer echo "Setup dependency: NBXplorer" @@ -208,7 +233,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 +273,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,9 +303,7 @@ 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" @@ -313,20 +311,41 @@ 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 + +# 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/plugins.json b/swagger/plugins.json new file mode 100644 index 0000000000..87a188ef75 --- /dev/null +++ b/swagger/plugins.json @@ -0,0 +1,14 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "BTCPay Server Greenfield Plugin API", + "version": "v1", + "description": "Plugin APIs for BTCPay Server" + }, + "servers": [ + { + "url": "/", + "description": "BTCPay Server Greenfield Plugin API" + } + ] +} From 701cdad8b28535e9ccd97156b46ca230ded5dc15 Mon Sep 17 00:00:00 2001 From: Dennis Reimann Date: Thu, 19 Oct 2023 12:20:20 +0200 Subject: [PATCH 2/4] Add gitkeep file --- swagger/plugins/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 swagger/plugins/.gitkeep diff --git a/swagger/plugins/.gitkeep b/swagger/plugins/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 From c776cabdfbffc380648678d2d3fe4eb4100b8a90 Mon Sep 17 00:00:00 2001 From: Dennis Reimann Date: Thu, 19 Oct 2023 12:34:42 +0200 Subject: [PATCH 3/4] Cross-reference API v1 docs --- swagger/plugins.json | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/swagger/plugins.json b/swagger/plugins.json index 87a188ef75..87e366c9cc 100644 --- a/swagger/plugins.json +++ b/swagger/plugins.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "BTCPay Server Greenfield Plugin API", - "version": "v1", + "version": "Plugins", "description": "Plugin APIs for BTCPay Server" }, "servers": [ @@ -10,5 +10,9 @@ "url": "/", "description": "BTCPay Server Greenfield Plugin API" } - ] + ], + "externalDocs": { + "description": "BTCPay Greenfield API (v1)", + "url": "https://docs.btcpayserver.org/API/Greenfield/v1/" + } } From 84fcd590df94f05a982598b6ef2cbfc61d233ec4 Mon Sep 17 00:00:00 2001 From: Dennis Reimann Date: Thu, 2 Nov 2023 14:41:29 +0100 Subject: [PATCH 4/4] Add external/plugin docs reference for core API docs --- setup-deps.sh | 61 ++++++++++++++++++++++++--------------------- swagger/btcpay.json | 6 +++++ 2 files changed, 39 insertions(+), 28 deletions(-) create mode 100644 swagger/btcpay.json diff --git a/setup-deps.sh b/setup-deps.sh index c02b87b1fd..28e8fd8a1a 100755 --- a/setup-deps.sh +++ b/setup-deps.sh @@ -55,34 +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) - -# 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 > $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 - # NBXplorer echo "Setup dependency: NBXplorer" @@ -325,6 +297,39 @@ 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 diff --git a/swagger/btcpay.json b/swagger/btcpay.json new file mode 100644 index 0000000000..76d93bfb62 --- /dev/null +++ b/swagger/btcpay.json @@ -0,0 +1,6 @@ +{ + "externalDocs": { + "description": "BTCPay Greenfield Plugins API", + "url": "https://docs.btcpayserver.org/API/Greenfield/Plugins/" + } +}