CBG-4240 Backport docs improvements to 3.1 branch (#7114)

.github/workflows/openapi-pr.yml

@@ -0,0 +1,44 @@
+# Copyright 2024-Present Couchbase, Inc.
+#
+# Use of this software is governed by the Business Source License included in
+# the file licenses/BSL-Couchbase.txt.  As of the Change Date specified in that
+# file, in accordance with the Business Source License, use of this software
+# will be governed by the Apache License, Version 2.0, included in the file
+# licenses/APL2.txt.
+
+name: openapi-pr
+
+on:
+  pull_request:
+    # Only run when we change an API spec
+    paths:
+      - 'docs/api/**'
+    branches:
+      - 'master'
+      - 'main'
+      - 'release/*'
+      - 'beryllium'
+
+jobs:
+  redocly_preview_links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Find Comment
+        uses: peter-evans/find-comment@v3
+        id: fc
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: Redocly previews
+      - name: Create or update comment
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            ## Redocly previews
+            - [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)
+            - [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)
+            - [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)
+            - [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)
+          edit-mode: replace

.github/workflows/openapi.yml

@@ -13,9 +13,12 @@ on:
     # Only run when we change an API spec
     paths:
       - 'docs/api/**'
-    branches: 
+    branches:
       - 'master'
+      - 'main'
       - 'release/*'
+      - 'feature/*'
+      - 'beryllium'
       - 'CBG*'
       - 'ci-*'
       - 'api-ci-*'
@@ -25,17 +28,28 @@ on:
       - 'docs/api/**'
     branches:
       - 'master'
+      - 'main'
       - 'release/*'
+      - 'beryllium'
 
 jobs:
   api_validation:
     runs-on: ubuntu-latest
     name: OpenAPI Validation
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: r7kamura/redocly-problem-matchers@v1
-      - uses: mhiew/redoc-lint-github-action@v3
+      - uses: mhiew/redoc-lint-github-action@v4
         with:
           args: '--format stylish'
         env:
           NO_COLOR: '1'
+
+  yamllint:
+    name: 'yamllint'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: karancode/yamllint-github-action@master
+        with:
+          yamllint_file_or_dir: 'docs/api'

.redocly.yaml

@@ -11,18 +11,61 @@
 apis:
   admin:
     root: "./docs/api/admin.yaml"
+    decorators:
+      remove-x-internal: on
+  admin-internal:
+    root: "./docs/api/admin.yaml"
+  admin-capella:
+    root: "./docs/api/admin-capella.yaml"
+    decorators:
+      filter-out:
+        property: x-capella
+        value: false
+      remove-x-internal: on
   public:
     root: "./docs/api/public.yaml"
+    decorators:
+      remove-x-internal: on
+  public-internal:
+    root: "./docs/api/public.yaml"
+  public-capella:
+    root: "./docs/api/public.yaml"
+    decorators:
+      filter-out:
+        property: x-capella
+        value: false
+      info-override:
+        description: "App Services manages access and synchronization between Couchbase Lite and Couchbase Capella"
+      plugin/replace-description-capella: on
+      plugin/replace-server-capella:
+        serverUrl: 'https://{hostname}:4984'
+      remove-x-internal: on
   metric:
     root: "./docs/api/metric.yaml"
+    decorators:
+      remove-x-internal: on
+  metric-internal:
+    root: "./docs/api/metric.yaml"
+  metric-capella:
+    root: "./docs/api/metric-capella.yaml"
+    decorators:
+      filter-out:
+        property: x-capella
+        value: false
+      plugin/excise-rbac-capella: on
+      plugin/replace-description-capella: on
+      remove-x-internal: on
+
+plugins:
+  - './docs/api/plugins/plugin.js'
 
-lint:
-  extends:
-    - minimal
-  rules:
-    # disable unnecessary/invalid warnings
-    operation-2xx-response: off # _blipsync 101 Upgrade ...
-    operation-summary: off      # Optional field
-    no-ambiguous-paths: off     # /{db}/{doc} != /_debug/expvar
-    no-identical-paths: off     # /{db} != /{targetdb}
-    no-path-trailing-slash: off # Some endpoints require a trailing slash
+extends:
+  - minimal
+rules:
+  # disable unnecessary/invalid warnings
+  operation-2xx-response: off # _blipsync 101 Upgrade ...
+  operation-summary: off      # Optional field
+  no-ambiguous-paths: off     # /{db}/{doc} != /_debug/expvar
+  no-identical-paths: off     # /{db} != /{targetdb}
+  no-path-trailing-slash: off # Some endpoints require a trailing slash
+  security-defined: off       # TODO: Denote public and authenticated API endpoints with https://redocly.com/docs/cli/rules/security-defined

.yamllint.yml

@@ -0,0 +1,17 @@
+# Copyright 2023-Present Couchbase, Inc.
+#
+# Use of this software is governed by the Business Source License included
+# in the file licenses/BSL-Couchbase.txt.  As of the Change Date specified
+# in that file, in accordance with the Business Source License, use of this
+# software will be governed by the Apache License, Version 2.0, included in
+# the file licenses/APL2.txt.
+
+---
+
+extends: default
+
+rules:
+  document-start: disable
+  line-length: disable
+  comments: disable
+  truthy: disable

docs/BUILD.md

@@ -1,5 +1,5 @@
 
-Building with Go Modules 
+Building with Go Modules
 ------------------------
 
 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
 
 After it's complete, you should see a message that says `Bootstrap complete!  Run ./build.sh to build and ./test.sh to run tests`
 
-*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`.  
+*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`.
 
 **Build and Test**
 

docs/BUILD_EXTRA.md

@@ -45,7 +45,7 @@ NOTE: you will get a lot of warnings from running this command.
 
 ```
 $ cd $GOPATH/src/github.com/couchbase/sync_gateway/
-$ go get -u 
+$ go get -u
 ```
 
 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

@@ -11,4 +11,4 @@ title: Sync Gateway
 version: '2.0'
 start_page: ROOT:installation.adoc
 nav:
-- modules/docs/nav.adoc
+  - modules/docs/nav.adoc

docs/api/README.md

@@ -0,0 +1,17 @@
+# Sync Gateway OpenAPI Specs
+
+This directory contains the OpenAPI specs for the Sync Gateway REST API.
+
+The recommended tool to work with these specs is [Redocly](https://redoc.ly/).
+
+## Preview
+
+```sh
+$ redocly preview-docs
+```
+
+## Linting
+
+```sh
+$ redocly lint
+```

docs/api/admin-capella.yaml

@@ -0,0 +1,42 @@
+# Copyright 2022-Present Couchbase, Inc.
+#
+# Use of this software is governed by the Business Source License included
+# in the file licenses/BSL-Couchbase.txt.  As of the Change Date specified
+# in that file, in accordance with the Business Source License, use of this
+# software will be governed by the Apache License, Version 2.0, included in
+# the file licenses/APL2.txt.
+
+openapi: 3.0.3
+info:
+  title: App Services Admin API
+  description: 'App Services manages access and synchronization between Couchbase Lite and Couchbase Capella'
+  version: '3.1'
+  license:
+    name: Business Source License 1.1 (BSL)
+    url: 'https://github.com/couchbase/sync_gateway/blob/master/LICENSE'
+servers:
+  - url: 'https://{hostname}:4985'
+    description: Admin API
+    variables:
+      hostname:
+        description: The hostname to use
+        default: localhost
+paths:
+  '/{db}/_session':
+    $ref: './paths/admin/db-_session.yaml'
+  '/{db}/_session/{sessionid}':
+    $ref: './paths/admin/db-_session-sessionid.yaml'
+  '/{db}/_user/{name}':
+    $ref: './paths/admin/db-_user-name.yaml'
+  '/{db}/_user/{name}/_session':
+    $ref: './paths/admin/db-_user-name-_session.yaml'
+  '/{db}/_user/{name}/_session/{sessionid}':
+    $ref: './paths/admin/db-_user-name-_session-sessionid.yaml'
+  '/{db}/_role/':
+    $ref: './paths/admin/db-_role-.yaml'
+  '/{db}/_role/{name}':
+    $ref: './paths/admin/db-_role-name.yaml'
+
+externalDocs:
+  description: Manage App Services for Mobile and Edge | Couchbase Docs
+  url: 'https://docs.couchbase.com/cloud/app-services/index.html'

docs/api/admin.yaml

@@ -10,7 +10,7 @@ openapi: 3.0.3
 info:
   title: Sync Gateway
   description: Sync Gateway manages access and synchronization between Couchbase Lite and Couchbase Server
-  version: 3.1.0
+  version: '3.1'
   license:
     name: Business Source License 1.1 (BSL)
     url: 'https://github.com/couchbase/sync_gateway/blob/master/LICENSE'

docs/api/components/parameters.yaml

@@ -65,13 +65,16 @@ keyspace:
   schema:
     type: string
   examples:
-    Default scope and collection:
+    default:
+      summary: Default scope and collection
       value: db1
       description: Default scope and collection
-    Named collection within the default scope:
+    namedInDefault:
+      summary: Named collection within the default scope
       value: db1.collection1
       description: Named collection within the default scope
-    Fully-qualified scope and collection:
+    fullyQualified:
+      summary: Fully-qualified scope and collection
       value: db1.scope1.collection1
       description: Fully-qualified scope and collection
   description: |-
@@ -111,6 +114,14 @@ docid:
     type: string
   example: doc1
   description: The document ID to run the operation against.
+doc_id:
+  name: doc_id
+  in: query
+  required: false
+  schema:
+    type: string
+  example: doc1
+  description: The document ID to run the operation against.
 endkey:
   name: endkey
   in: query

docs/api/components/responses.yaml

@@ -180,3 +180,15 @@ DB-config-precondition-failed:
       example:
         error: Precondition Failed
         reason: Provided If-Match header does not match current config version
+All_user_channels_response:
+  description: Map of all keyspaces to all channels that the user has access to.
+  content:
+    application/json:
+      schema:
+        $ref: ./schemas.yaml#/all_user_channels
+user_access_span_response:
+  description: Grant history entries for a user, showing which documents the user had access to, through which channels and for which sequence spans..
+  content:
+    application/json:
+      schema:
+        $ref: ./schemas.yaml#/doc_access_spans