Skip to content

Commit 4c4fca0

Browse files
adamcfraseradamcfraser
authored
CBG-4240 Backport docs improvements to 3.1 branch (#7114)
1 parent 5ba7cd0 commit 4c4fca0

36 files changed

+901
-188
lines changed

‎.github/workflows/openapi-pr.yml

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Copyright 2024-Present Couchbase, Inc.
2+
#
3+
# Use of this software is governed by the Business Source License included in
4+
# the file licenses/BSL-Couchbase.txt. As of the Change Date specified in that
5+
# file, in accordance with the Business Source License, use of this software
6+
# will be governed by the Apache License, Version 2.0, included in the file
7+
# licenses/APL2.txt.
8+
9+
name: openapi-pr
10+
11+
on:
12+
pull_request:
13+
# Only run when we change an API spec
14+
paths:
15+
- 'docs/api/**'
16+
branches:
17+
- 'master'
18+
- 'main'
19+
- 'release/*'
20+
- 'beryllium'
21+
22+
jobs:
23+
redocly_preview_links:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Find Comment
27+
uses: peter-evans/find-comment@v3
28+
id: fc
29+
with:
30+
issue-number: ${{ github.event.pull_request.number }}
31+
comment-author: 'github-actions[bot]'
32+
body-includes: Redocly previews
33+
- name: Create or update comment
34+
uses: peter-evans/create-or-update-comment@v4
35+
with:
36+
comment-id: ${{ steps.fc.outputs.comment-id }}
37+
issue-number: ${{ github.event.pull_request.number }}
38+
body: |
39+
## Redocly previews
40+
- [Admin API](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/couchbase/sync_gateway/${{ github.event.pull_request.head.sha }}/docs/api/admin.yaml)
41+
- [Public API](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/couchbase/sync_gateway/${{ github.event.pull_request.head.sha }}/docs/api/public.yaml)
42+
- [Metric API](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/couchbase/sync_gateway/${{ github.event.pull_request.head.sha }}/docs/api/metric.yaml)
43+
- [Diagnostic API](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/couchbase/sync_gateway/${{ github.event.pull_request.head.sha }}/docs/api/diagnostic.yaml)
44+
edit-mode: replace

‎.github/workflows/openapi.yml

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,12 @@ on:
1313
# Only run when we change an API spec
1414
paths:
1515
- 'docs/api/**'
16-
branches:
16+
branches:
1717
- 'master'
18+
- 'main'
1819
- 'release/*'
20+
- 'feature/*'
21+
- 'beryllium'
1922
- 'CBG*'
2023
- 'ci-*'
2124
- 'api-ci-*'
@@ -25,17 +28,28 @@ on:
2528
- 'docs/api/**'
2629
branches:
2730
- 'master'
31+
- 'main'
2832
- 'release/*'
33+
- 'beryllium'
2934

3035
jobs:
3136
api_validation:
3237
runs-on: ubuntu-latest
3338
name: OpenAPI Validation
3439
steps:
35-
- uses: actions/checkout@v2
40+
- uses: actions/checkout@v4
3641
- uses: r7kamura/redocly-problem-matchers@v1
37-
- uses: mhiew/redoc-lint-github-action@v3
42+
- uses: mhiew/redoc-lint-github-action@v4
3843
with:
3944
args: '--format stylish'
4045
env:
4146
NO_COLOR: '1'
47+
48+
yamllint:
49+
name: 'yamllint'
50+
runs-on: ubuntu-latest
51+
steps:
52+
- uses: actions/checkout@v4
53+
- uses: karancode/yamllint-github-action@master
54+
with:
55+
yamllint_file_or_dir: 'docs/api'

‎.redocly.yaml

Lines changed: 53 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,61 @@
1111
apis:
1212
admin:
1313
root: "./docs/api/admin.yaml"
14+
decorators:
15+
remove-x-internal: on
16+
admin-internal:
17+
root: "./docs/api/admin.yaml"
18+
admin-capella:
19+
root: "./docs/api/admin-capella.yaml"
20+
decorators:
21+
filter-out:
22+
property: x-capella
23+
value: false
24+
remove-x-internal: on
1425
public:
1526
root: "./docs/api/public.yaml"
27+
decorators:
28+
remove-x-internal: on
29+
public-internal:
30+
root: "./docs/api/public.yaml"
31+
public-capella:
32+
root: "./docs/api/public.yaml"
33+
decorators:
34+
filter-out:
35+
property: x-capella
36+
value: false
37+
info-override:
38+
description: "App Services manages access and synchronization between Couchbase Lite and Couchbase Capella"
39+
plugin/replace-description-capella: on
40+
plugin/replace-server-capella:
41+
serverUrl: 'https://{hostname}:4984'
42+
remove-x-internal: on
1643
metric:
1744
root: "./docs/api/metric.yaml"
45+
decorators:
46+
remove-x-internal: on
47+
metric-internal:
48+
root: "./docs/api/metric.yaml"
49+
metric-capella:
50+
root: "./docs/api/metric-capella.yaml"
51+
decorators:
52+
filter-out:
53+
property: x-capella
54+
value: false
55+
plugin/excise-rbac-capella: on
56+
plugin/replace-description-capella: on
57+
remove-x-internal: on
58+
59+
plugins:
60+
- './docs/api/plugins/plugin.js'
1861

19-
lint:
20-
extends:
21-
- minimal
22-
rules:
23-
# disable unnecessary/invalid warnings
24-
operation-2xx-response: off # _blipsync 101 Upgrade ...
25-
operation-summary: off # Optional field
26-
no-ambiguous-paths: off # /{db}/{doc} != /_debug/expvar
27-
no-identical-paths: off # /{db} != /{targetdb}
28-
no-path-trailing-slash: off # Some endpoints require a trailing slash
62+
extends:
63+
- minimal
64+
rules:
65+
# disable unnecessary/invalid warnings
66+
operation-2xx-response: off # _blipsync 101 Upgrade ...
67+
operation-summary: off # Optional field
68+
no-ambiguous-paths: off # /{db}/{doc} != /_debug/expvar
69+
no-identical-paths: off # /{db} != /{targetdb}
70+
no-path-trailing-slash: off # Some endpoints require a trailing slash
71+
security-defined: off # TODO: Denote public and authenticated API endpoints with https://redocly.com/docs/cli/rules/security-defined

‎.yamllint.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Copyright 2023-Present Couchbase, Inc.
2+
#
3+
# Use of this software is governed by the Business Source License included
4+
# in the file licenses/BSL-Couchbase.txt. As of the Change Date specified
5+
# in that file, in accordance with the Business Source License, use of this
6+
# software will be governed by the Apache License, Version 2.0, included in
7+
# the file licenses/APL2.txt.
8+
9+
---
10+
11+
extends: default
12+
13+
rules:
14+
document-start: disable
15+
line-length: disable
16+
comments: disable
17+
truthy: disable

‎docs/BUILD.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11

2-
Building with Go Modules
2+
Building with Go Modules
33
------------------------
44

55
Recent versions of Sync Gateway provide support for Go modules, which simplifies the process of building from source. Older versions will require building with pinned dependencies, see below.
@@ -45,7 +45,7 @@ $ ./bootstrap.sh
4545

4646
After it's complete, you should see a message that says `Bootstrap complete! Run ./build.sh to build and ./test.sh to run tests`
4747

48-
*Note:* if you want to run the bootstrap initialization and start on a particular Sync Gateway commit, you can provide the `-c` flag, eg `./bootstrap.sh -c y0pl33g0r425`.
48+
*Note:* if you want to run the bootstrap initialization and start on a particular Sync Gateway commit, you can provide the `-c` flag, eg `./bootstrap.sh -c y0pl33g0r425`.
4949

5050
**Build and Test**
5151

‎docs/BUILD_EXTRA.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ NOTE: you will get a lot of warnings from running this command.
4545

4646
```
4747
$ cd $GOPATH/src/github.com/couchbase/sync_gateway/
48-
$ go get -u
48+
$ go get -u
4949
```
5050

5151
Running `go get` here will put your Sync Gateway back on the master branch, so you'll need to go *back* to the feature branch again:

‎docs/antora.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ title: Sync Gateway
1111
version: '2.0'
1212
start_page: ROOT:installation.adoc
1313
nav:
14-
- modules/docs/nav.adoc
14+
- modules/docs/nav.adoc

‎docs/api/README.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Sync Gateway OpenAPI Specs
2+
3+
This directory contains the OpenAPI specs for the Sync Gateway REST API.
4+
5+
The recommended tool to work with these specs is [Redocly](https://redoc.ly/).
6+
7+
## Preview
8+
9+
```sh
10+
$ redocly preview-docs
11+
```
12+
13+
## Linting
14+
15+
```sh
16+
$ redocly lint
17+
```

‎docs/api/admin-capella.yaml

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Copyright 2022-Present Couchbase, Inc.
2+
#
3+
# Use of this software is governed by the Business Source License included
4+
# in the file licenses/BSL-Couchbase.txt. As of the Change Date specified
5+
# in that file, in accordance with the Business Source License, use of this
6+
# software will be governed by the Apache License, Version 2.0, included in
7+
# the file licenses/APL2.txt.
8+
9+
openapi: 3.0.3
10+
info:
11+
title: App Services Admin API
12+
description: 'App Services manages access and synchronization between Couchbase Lite and Couchbase Capella'
13+
version: '3.1'
14+
license:
15+
name: Business Source License 1.1 (BSL)
16+
url: 'https://github.com/couchbase/sync_gateway/blob/master/LICENSE'
17+
servers:
18+
- url: 'https://{hostname}:4985'
19+
description: Admin API
20+
variables:
21+
hostname:
22+
description: The hostname to use
23+
default: localhost
24+
paths:
25+
'/{db}/_session':
26+
$ref: './paths/admin/db-_session.yaml'
27+
'/{db}/_session/{sessionid}':
28+
$ref: './paths/admin/db-_session-sessionid.yaml'
29+
'/{db}/_user/{name}':
30+
$ref: './paths/admin/db-_user-name.yaml'
31+
'/{db}/_user/{name}/_session':
32+
$ref: './paths/admin/db-_user-name-_session.yaml'
33+
'/{db}/_user/{name}/_session/{sessionid}':
34+
$ref: './paths/admin/db-_user-name-_session-sessionid.yaml'
35+
'/{db}/_role/':
36+
$ref: './paths/admin/db-_role-.yaml'
37+
'/{db}/_role/{name}':
38+
$ref: './paths/admin/db-_role-name.yaml'
39+
40+
externalDocs:
41+
description: Manage App Services for Mobile and Edge | Couchbase Docs
42+
url: 'https://docs.couchbase.com/cloud/app-services/index.html'

‎docs/api/admin.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ openapi: 3.0.3
1010
info:
1111
title: Sync Gateway
1212
description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
13-
version: 3.1.0
13+
version: '3.1'
1414
license:
1515
name: Business Source License 1.1 (BSL)
1616
url: 'https://github.com/couchbase/sync_gateway/blob/master/LICENSE'

0 commit comments

Comments
 (0)