Skip to content

Commit 2cf2c1f

Browse files
simon-dewsimon-dew
committed
DOC-13291: Fix tech debt (#876)
* Update N1QL to SQL++ * Remove swagger2markup artifacts * Remove openapi-generator artifacts * Update gitignore * Driveby fixes * Replace OpenAPI Generator templates * Fix example files * Update files which include static REST API content * Tweaks for static REST API output * Rebuild output docs
1 parent 2e7b611 commit 2cf2c1f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+33579
-39400
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -414,3 +414,6 @@ modules/ROOT/assets/attachments/.DS_Store
414414
#Asciidoctor configuration
415415
**/.asciidoctorconfig
416416

417+
#OpenAPI Generator files
418+
.openapi-generator
419+
.openapi-generator-ignore

‎modules/ROOT/examples/configuration/sync-gateway-config.json‎

Lines changed: 68 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -864,41 +864,49 @@ function sync(doc, oldDoc) {
864864

865865

866866
// tag::icr-repl-create-pull-oneshot[]
867-
//. . . other configuration entries
868-
"db1-rep-id3-pull-oneshot":
867+
{
868+
// . . . other configuration entries
869+
"db1-rep-id3-pull-oneshot": {
869870
// tag::icr-repl-create-pull-oneshot-body[]
870-
"replication_id": "db1-rep-id3-pull-oneshot", // <.>
871-
"direction": "pull",
872-
"remote": "http://user1:password@example.com:4985/db1-remote", // <.>
873-
"filter": "sync_gateway/bychannel",
874-
"query_params": { "channels": ["channel1.user1"] }
871+
"replication_id": "db1-rep-id3-pull-oneshot", // <.>
872+
"direction": "pull",
873+
"remote": "http://user1:password@example.com:4985/db1-remote", // <.>
874+
"filter": "sync_gateway/bychannel",
875+
"query_params": {
876+
"channels": ["channel1.user1"]
877+
}
875878
// end::icr-repl-create-pull-oneshot-body[]
879+
}
876880
// . . . other configuration entries
881+
}
877882
// end::icr-repl-create-pull-oneshot[]
878883

879884
// tag::icr-repl-create-pull-oneshot-callouts[]
880-
<.> This a a one-shot replication because the `continuous` parameter defaults to `false`.
885+
<.> This a one-shot replication because the `continuous` parameter defaults to `false`.
881886

882887
<.> The remote URL can also include the credentials for an existing Sync Gateway user on the remote server.
883888

884889
// end::icr-repl-create-pull-oneshot-callouts[]
885890

886891

887892
// tag::icr-repl-create-pull-cont[]
893+
{
888894
// . . . other configuration entries
889-
"db1-rep-id1-pull-cont":
895+
"db1-rep-id1-pull-cont": {
890896
// tag::icr-repl-create-pull-cont-body[]
891-
"replication_id": "db1-rep-id1-pull-cont",
892-
"direction": "pull",
893-
"continuous": true // <.>
894-
"purge-on-removal": true,
895-
"remote": "http://user:password@example.com:4985/db1-remote",
896-
"filter":"sync_gateway/bychannel",
897-
"query_params": {
898-
"channels": ["channel1.user1"]
899-
}
897+
"replication_id": "db1-rep-id1-pull-cont",
898+
"direction": "pull",
899+
"continuous": true, // <.>
900+
"purge-on-removal": true,
901+
"remote": "http://user:password@example.com:4985/db1-remote", //<.>
902+
"filter":"sync_gateway/bychannel",
903+
"query_params": {
904+
"channels": ["channel1.user1"]
905+
}
900906
// end::icr-repl-create-pull-cont-body[]
907+
}
901908
// . . . other configuration entries
909+
}
902910
// end::icr-repl-create-pull-cont[]
903911

904912
// tag::icr-repl-create-pull-cont-callouts[]
@@ -908,7 +916,7 @@ Because it is also persistent, it will start automatically following Sync Gatewa
908916
<.> The remote URL can also include the credentials for an existing Sync Gateway user on the remote server.
909917
// end::icr-repl-create-pull-cont-callouts[]
910918

911-
919+
{
912920
// tag::icr-repl-adhoc-pull-body[]
913921
"replication_id": "db1-rep-id1-pull-adhoc",
914922
"adhoc": true, // <.>
@@ -920,58 +928,66 @@ Because it is also persistent, it will start automatically following Sync Gatewa
920928
"channels": ["channel1.user1"]
921929
}
922930
// end::icr-repl-adhoc-pull-body[]
931+
}
923932

924933
// tag::icr-repl-adhoc-pull-callouts[]
925934
<.> Run this replication as an ad hoc one. It will run once only, process all changes but not survive Sync Gateway restarts
926935
// end::icr-repl-adhoc-pull-callouts[]
927936

928937

929938
// tag::icr-rep-sample-create-pull[]
930-
"databases": {
931-
" db1": { // <.>
939+
{
940+
"db1": { // <.>
932941
"bucket":"db1",
933942
"server": "couchbase://cb-server",
934943
// ... other DB config ..
935944
"sgreplicate_enabled": true, // <.>
936-
"replications":
937-
"db1-rep-id1-pull-oneshot": // <.>
938-
// tag::icr-rep-sample-create-pull-body[]
939-
"direction": "pull", // <.>
940-
"remote": "https://example.com:4984/remote_db1",
941-
"user": "user1", // <.>
942-
"password": "password",
943-
"batch_size": 1000, // <.>
944-
"conflict_resolution_type": "custom", // <.>
945-
"custom_conflict_resolver": "", // <.>
946-
"continuous": false, // <.>
947-
"enable_delta_sync": false, // <.>
948-
"filter": "sync_gateway/bychannel", // <.>
949-
"query_params": ["channel.user1"] // <.>
950-
"max_backoff_time": 5, // <.>
951-
"purge_on_removal": false // <.>
952-
"state": "running" // <.>
953-
// end::icr-rep-sample-create-pull-body[]
945+
"replications": {
946+
"db1-rep-id1-pull-oneshot": { // <.>
947+
// tag::icr-rep-sample-create-pull-body[]
948+
"direction": "pull", // <.>
949+
"remote": "https://example.com:4984/remote_db1",
950+
"user": "user1", // <.>
951+
"password": "password",
952+
"batch_size": 1000, // <.>
953+
"conflict_resolution_type": "custom", // <.>
954+
"custom_conflict_resolver": "", // <.>
955+
"continuous": false, // <.>
956+
"enable_delta_sync": false, // <.>
957+
"filter": "sync_gateway/bychannel", // <.>
958+
"query_params": ["channel.user1"], // <.>
959+
"max_backoff_time": 5, // <.>
960+
"purge_on_removal": false, // <.>
961+
"state": "running", // <.>
962+
// end::icr-rep-sample-create-pull-body[]
963+
// ... other replication config ...
964+
}
965+
}
954966
}
955967
}
956968
// end::icr-rep-sample-create-pull[]
957969

958970
// tag::icr-rep-sample-create-pull-callouts-full[]
959-
<.> All replications are defined at database level within the context of a local database (e.g. `DB1`)
960-
<.> Opt in to replication
961-
<.> Define the `replication_id`
971+
<.> All replications are defined at database level within the context of a local database, for example `db1`.
972+
<.> Opt in to replication.
973+
<.> Define the `replication_id`.
962974
// tag::icr-rep-sample-create-pull-callouts[]
963-
<.> Pull changes from the `remote` database at the specified url. +
964-
<.> Authenticate with the provided credentials. This user must have read and write access to both the local and remote databases. +
965-
<.> Batch together up to 1000 revisions at a time. This improve replication performance but consumes more memory resources. +
966-
<.> Apply a custom conflict resolution policy. +
975+
<.> Pull changes from the `remote` database at the specified url.
976+
<.> Authenticate with the provided credentials.
977+
This user must have read and write access to both the local and remote databases.
978+
<.> Batch together up to 1000 revisions at a time.
979+
This improves replication performance but consumes more memory resources.
980+
<.> Apply a custom conflict resolution policy.
967981
<.> Provide a working Javascript function to apply the required resolution policy.
968-
<.> By setting continuous=false, we are creating a one-shot replication. We could also have omitted this parameter as it defaults to `false`.
982+
<.> By setting continuous=`false`, this creates a one-shot replication.
983+
You could omit this parameter as it defaults to `false`.
969984
<.> Don't use delta-sync; the default behavior.
970-
<.> Filter documents by channel. +
971-
<.> Replicate only those documents tagged with the channel names "user1". +
972-
<.> Wait no more than 5 minutes between retries after network failure; default behavior. +
973-
<.> Don't purge following removal of a channel; the default behavior. +
974-
<.> Start the replicator immediately and on Sync Gateway node re(start);. We could also have omitted this parameter as this is the default behavior.
985+
<.> Filter documents by channel.
986+
<.> Replicate only those documents tagged with the channel names "user1".
987+
<.> Wait no more than 5 minutes between retries after network failure; default behavior.
988+
<.> Don't purge following removal of a channel; the default behavior.
989+
<.> Start the replicator immediately and on Sync Gateway node re(start);.
990+
You could omit this parameter as this is the default behavior.
975991
// end::icr-rep-sample-create-pull-callouts[]
976992
// end::icr-rep-sample-create-pull-callouts-full[]
977993

‎modules/ROOT/examples/configuration/sync-gateway-restapi.adoc‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,23 +15,23 @@ include::{example-cfg}[tags=icr-sample-sync-gateway-config-replication-body]
1515
curl --location --request POST 'http://localhost:4985/db1-local/_replication/' \
1616
--header 'Content-Type: application/json' \
1717
--dataraw '{
18-
include::{example-cfg}[tags=icr-repl-create-pull-oneshot-body]
18+
include::{example-cfg}[tags=icr-repl-create-pull-oneshot-body,indent=2]
1919
}'
2020
// end::icr-repl-create-pull-oneshot[]
2121

2222
// tag::icr-repl-create-pull-cont[]
2323
curl --location --request POST 'http://localhost:4985/db1-local/_replication/' \
2424
--header 'Content-Type: application/json' \
2525
--dataraw '{
26-
include::{example-cfg}[tags=icr-repl-create-pull-cont-body]
26+
include::{example-cfg}[tags=icr-repl-create-pull-cont-body,indent=2]
2727
}'
2828
// end::icr-repl-create-pull-cont[]
2929

3030
// tag::icr-repl-adhoc-pull[]
3131
curl --location --request POST 'http://localhost:4985/db1-local/_replication/' \
3232
--header 'Content-Type: application/json' \
3333
--dataraw '{
34-
include::{example-cfg}[tags=icr-repl-adhoc-pull-body]
34+
include::{example-cfg}[tags=icr-repl-adhoc-pull-body,indent=2]
3535
}'
3636
// end::icr-repl-adhoc-pull[]
3737

@@ -478,24 +478,28 @@ curl --location --request POST 'http://localhost:4985/local_db1/_replication/' \
478478

479479
// tag::icr-rep-sample-create-pull[]
480480
// tag::icr-rep-sample-create-pull-curl[]
481-
curl --location --request POST 'http://localhost:4985/db1-local/_replication/db1-rep-id1-pull-oneshot' \ // <.>
481+
curl --location --request POST \
482+
'http://localhost:4985/db1-local/_replication/db1-rep-id1-pull-oneshot' \ <.>
482483
--header 'Content-Type: application/json' \
483484
--dataraw '{
484485
// end::icr-rep-sample-create-pull-curl[]
485486
// tag::icr-rep-sample-create-pull-body[]
486-
"replication_id": "db1-rep-id1-pull-oneshot" // <.>
487-
include::{example-cfg}[tags=icr-rep-sample-create-pull-body]
488-
"adhoc": false, // <.>
489-
"cancel": false // <.>
487+
"replication_id": "db1-rep-id1-pull-oneshot", // <.>
488+
include::{example-cfg}[tags=icr-rep-sample-create-pull-body,indent=2]
489+
"adhoc": false, // <.>
490+
"cancel": false // <.>
490491
}'
491492
// end::icr-rep-sample-create-pull-body[]
492493
// end::icr-rep-sample-create-pull[]
493494

494495

495496
// tag::icr-rep-sample-create-pull-callouts[]
496-
<.> All replications take place at database level and in the context of a local database. Here we are setting the replication in the context of `db1-local`
497-
<.> Define the `replication_id`
497+
<.> All replications take place at database level and in the context of a local database.
498+
This sets the replication in the context of `db1-local`.
499+
<.> Define the `replication_id`.
498500
include::{example-cfg}[tags=icr-rep-sample-create-pull-callouts]
499-
<.> Setting `adhoc=false` marks this as a persistent replication. The definition will survive Sync Gateway node restarts. This the default behaviour if this parameter is omitted.+
501+
<.> Setting `adhoc=false` marks this as a persistent replication.
502+
The definition will survive Sync Gateway node restarts.
503+
This the default behavior if this parameter is omitted.
500504
<.> Set `cancel=true` to cancel an initialized replication; otherwise you can omit this parameter.
501505
// end::icr-rep-sample-create-pull-callouts[]

‎modules/ROOT/generate-docs.sh‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/bin/sh
2+
3+
set -exuo pipefail
4+
5+
cd $(dirname "${BASH_SOURCE[0]}")
6+
7+
GIT_ROOT=$(git rev-parse --show-toplevel)
8+
cd "${GIT_ROOT}"
9+
10+
# Get docs tag name from current major.minor version
11+
yq -V || brew install yq
12+
tag=$(yq -r .version antora.yml)-docs
13+
14+
# Get upstream sync_gateway repo
15+
git clone --no-checkout https://github.com/couchbase/sync_gateway.git
16+
cd sync_gateway
17+
git sparse-checkout init --cone
18+
git sparse-checkout set docs/api
19+
# check & delete local tag in case remote tag has been moved
20+
has_tag=$(git tag -l ${tag})
21+
if [[ -n ${has_tag} ]]; then
22+
git tag -d ${tag}
23+
fi
24+
# update remote tags after deleting local ones
25+
git fetch --tags
26+
git reset --hard ${tag}
27+
cd ..
28+
29+
PATH_TO_SYNC_GATEWAY="${GIT_ROOT}/sync_gateway"
30+
31+
PATH_TO_BUNDLE="${GIT_ROOT}/modules/ROOT/assets/attachments"
32+
PATH_TO_STATIC="${GIT_ROOT}/modules/ROOT/pages/_partials/static_restapi"
33+
34+
cd modules/ROOT
35+
36+
generate() {
37+
WHAT=$1
38+
39+
# Build the bundled spec using Redocly CLI.
40+
npx '@redocly/cli' bundle \
41+
--config "${PATH_TO_SYNC_GATEWAY}/.redocly.yaml" \
42+
"${WHAT}" \
43+
--dereferenced \
44+
--output "${PATH_TO_BUNDLE}/bundled-${WHAT}.yaml"
45+
46+
# Build the static output using the bundled spec.
47+
npx @openapitools/openapi-generator-cli generate \
48+
--skip-validate-spec \
49+
--generator-name asciidoc \
50+
--input-spec "${PATH_TO_BUNDLE}/bundled-${WHAT}.yaml" \
51+
--template-dir "${PATH_TO_STATIC}/templates" \
52+
--additional-properties skipExamples=true \
53+
--additional-properties useTableTitles=true \
54+
--output "${PATH_TO_STATIC}/${WHAT}"
55+
}
56+
57+
generate public
58+
generate admin
59+
generate metric
60+
61+
# Clear upstream repo
62+
rm -rf "${PATH_TO_SYNC_GATEWAY}"

‎modules/ROOT/openapitools.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
3+
"spaces": 2,
4+
"generator-cli": {
5+
"version": "7.13.0"
6+
}
7+
}

0 commit comments

Comments
 (0)