Skip to content

Commit a80cd61

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 1866d49 commit a80cd61

65 files changed

Lines changed: 40387 additions & 48841 deletions

Some content is hidden

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

‎.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+
"initial_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: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ PATH_TO_SYNC_GATEWAY="${GIT_ROOT}/sync_gateway"
3131
PATH_TO_BUNDLE="${GIT_ROOT}/modules/ROOT/assets/attachments"
3232
PATH_TO_OVERLAY="${GIT_ROOT}/modules/ROOT/assets/overlays"
3333
PATH_TO_TEMP="${GIT_ROOT}/modules/ROOT/assets/bld"
34+
PATH_TO_STATIC="${GIT_ROOT}/modules/ROOT/pages/_partials/static_restapi"
3435

3536
# Create a bld directory to hold temporary files, if it doesn't already exist
3637
[[ -d "${PATH_TO_TEMP}" ]] || mkdir "${PATH_TO_TEMP}"
@@ -72,6 +73,15 @@ generate() {
7273
"${PATH_TO_TEMP}/${WHAT}.yaml" \
7374
--output partials/sgw-openapi-$WHAT.html \
7475
--template partials/redocAll.hbs
76+
77+
# Build the static output using the overlaid spec.
78+
npx @openapitools/openapi-generator-cli generate \
79+
--skip-validate-spec \
80+
--generator-name asciidoc \
81+
--input-spec "${PATH_TO_TEMP}/${WHAT}.yaml" \
82+
--template-dir "${PATH_TO_STATIC}/templates" \
83+
--additional-properties skipExamples=true \
84+
--output "${PATH_TO_STATIC}/${WHAT}"
7585
}
7686

7787
generate public

‎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+
}

‎modules/ROOT/pages/_partials/incpg-icr-initialization.adoc‎

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -122,27 +122,24 @@ A number of database-level options are also especially relevant to Inter-Sync{nb
122122

123123
=== Replication-level Settings
124124

125+
This table summarizes all the available configurable items.
126+
127+
.Summary of Parameters
128+
include::partial$static_restapi/admin/index.adoc[tags=User_configurable_replication_properties]
129+
125130
[[replication-properties]]
126131
.Replication Definition
127132
=====
128133
129134
[{tabs}]
130135
====
131-
132-
Summary of Parameters::
133-
+
134-
--
135-
This table summarize all the available configurable items.
136-
137-
include::partial$static_restapi/admin/definitions.adoc[tags=replication_model_table]
138-
--
139-
140136
Configured Example::
141137
+
142138
--
143-
This is an example of a replication definition. Its purpose is to illustrate all configurable items in use and so should not be considered a working example.
139+
This is an example of a replication definition.
140+
Its purpose is to illustrate configurable items in use, and so should not be considered a working example.
144141

145-
It creates a replication with the replication_ID of `db1-rep-id1-pull-oneshot` on a local database `db1-local_`, pulling data from a remote database `db1-remote`.
142+
It creates a replication with the replication_ID of `db1-rep-id1-pull-oneshot` on a local database `db1-local`, pulling data from a remote database `remote-db1`.
146143

147144
[source, json]
148145
----
@@ -157,10 +154,11 @@ REST API Example::
157154
+
158155
--
159156
This is an example of a replication definition as you might submit it to the Admin REST API.using `curl`.
160-
Its purpose is to illustrate all configurable items in use and so should not be considered a working example.
157+
Its purpose is to illustrate configurable items in use, and so should not be considered a working example.
161158

162159
It creates a replication with the replication_ID of `db1-rep-id1-pull-oneshot` on a local database `db1-local_`, pulling data from a remote database `db1-remote`.
163-
[source, json]
160+
161+
[source, bash]
164162
----
165163
include::{example-restapi}[tag=icr-rep-sample-create-pull, indent=0]
166164
----
@@ -195,7 +193,7 @@ However, you should avoid initializing identical pre-2.8 (SG Replicate) and 2.8+
195193

196194
== Running Configured Replications
197195
Replications in the configuration file start automatically whenever Sync Gateway is (re)started.
198-
Unless you inhibit this by adding an `"initial_state": "stopped"` parameter to the replication definition -- see: {configuration-schema-database--xref--db-rep-initial_state}.
196+
Unless you inhibit this by adding an `"initial_state": "stopped"` parameter to the replication definition -- see: xref:configuration-schema-database.adoc#replications-replication_id-initial_state[initial_state].
199197
You can manually start 'stopped' replication using {sync-inter-syncgateway-manage--xref-start}.
200198

201199
.Configured Replications -- Continuous and One-shot
@@ -248,12 +246,12 @@ Continuous Pull Replication::
248246
--
249247
This example initializes a persistent, continuous, replication between a local database and one on a remote Sync Gateway instance.
250248

251-
[source, json]
249+
[source, bash]
252250
----
253251
include::{example-restapi}[tag=icr-repl-create-pull-cont]
254252
----
255253

256-
include::{example-cfg}[tag=icr-rep-create-pull-cont-callouts]
254+
include::{example-cfg}[tag=icr-repl-create-pull-cont-callouts]
257255

258256
--
259257

@@ -265,7 +263,7 @@ This example initializes a persistent, one-shot, replication between a local dat
265263
The replication will run once, after a short delay to allow the Rest API to start.
266264
It will then run once after each Sync Gateway restart and-or when manually initiated using the `_replicationStatus` endpoint -- see {sync-inter-syncgateway-manage--xref}.
267265

268-
[source, json]
266+
[source, bash]
269267
----
270268
include::{example-restapi}[tags=icr-repl-create-pull-oneshot]
271269
----
@@ -278,7 +276,7 @@ Ad-hoc::
278276
+
279277
--
280278

281-
[source,javascript]
279+
[source, bash]
282280
----
283281
include::{example-restapi}[tags=icr-repl-adhoc-pull]
284282
----

‎modules/ROOT/pages/_partials/static_restapi/.openapi-generator-ignore‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎modules/ROOT/pages/_partials/static_restapi/.openapi-generator/FILES‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)