[3.2.4 backport] CBG-4588 use natural language for openapi

db/attachment_test.go

@@ -883,7 +883,7 @@ func TestMigrateBodyAttachments(t *testing.T) {
 		defer db.Close(ctx)
 		collection, ctx := GetSingleDatabaseCollectionWithUser(ctx, t, db)
 
-		// Update the doc with a the same body as rev 3-a, and make sure attachments are migrated.
+		// Update the doc with the same body as rev 3-a, and make sure attachments are migrated.
 		newBody := Body{
 			"test":  true,
 			BodyRev: "3-a",

docs/api/admin.yaml

@@ -198,8 +198,6 @@ tags:
     description: Create and manage database users and roles
   - name: Session
     description: Manage user sessions
-  - name: OpenID Connect
-    description: Manage OpenID Connect
   - name: Document
     description: Create and manage documents and attachments
   - name: Replication

docs/api/components/schemas.yaml

@@ -697,7 +697,7 @@ Retrieved-replication:
         - localWins
         - custom
     custom_conflict_resolver:
-      description: "This specifies the Javascript function to use to resolve conflicts between conflicting revisions.\n \nThis **must** be used when `conflict_resolution_type=custom`. This property will be ignored when `conflict_resolution_type` is not `custom`.\n\nThe Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties:\n* `LocalDocument` - The local document. This contains the document ID under the `_id` key.\n* `RemoteDocument` - The remote document\nThe function should return the new documents body. This can be the winning revision (for example, `return conflict.LocalDocument`), a new body, or `nil` to resolve as a delete.\n\nExample:\n```\n\"custom_conflict_resolver\":\\`\n\tfunction(conflict) {\n\t\tconsole.log(\"Doc ID: \"+conflict.LocalDocument._id);\n\t\tconsole.log(\"Full remote doc: \"+JSON.stringify(conflict.RemoteDocument));\n\t\treturn conflict.RemoteDocument;\n\t}\n\\`\n```\n\nUsing complex `custom_conflict_resolver` functions can noticeably degrade performance. Use a built-in resolver whenever possible.\n\nThis is an Enterprise Edition only feature.\n"
+      description: "This specifies the Javascript function to use to resolve conflicts between conflicting revisions.\n \nThis **must** be used when `conflict_resolution_type=custom`. This property will be ignored when `conflict_resolution_type` is not `custom`.\n\nThe Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties:\n* `LocalDocument` - The local document. This contains the document ID under the `_id` key.\n* `RemoteDocument` - The remote document\nThe function should return the new document's body. This can be the winning revision (for example, `return conflict.LocalDocument`), a new body, or `nil` to resolve as a delete.\n\nExample:\n```\n\"custom_conflict_resolver\":\\`\n\tfunction(conflict) {\n\t\tconsole.log(\"Doc ID: \"+conflict.LocalDocument._id);\n\t\tconsole.log(\"Full remote doc: \"+JSON.stringify(conflict.RemoteDocument));\n\t\treturn conflict.RemoteDocument;\n\t}\n\\`\n```\n\nUsing complex `custom_conflict_resolver` functions can noticeably degrade performance. Use a built-in resolver whenever possible.\n\nThis is an Enterprise Edition only feature.\n"
       type: string
       default: none
     purge_on_removal:
@@ -925,7 +925,7 @@ Replication:
         - localWins
         - custom
     custom_conflict_resolver:
-      description: "This specifies the Javascript function to use to resolve conflicts between conflicting revisions.\n \nThis **must** be used when `conflict_resolution_type=custom`. This property will be ignored when `conflict_resolution_type` is not `custom`.\n\nThe Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties:\n* `LocalDocument` - The local document. This contains the document ID under the `_id` key.\n* `RemoteDocument` - The remote document\nThe function should return the new documents body. This can be the winning revision (for example, `return conflict.LocalDocument`), a new body, or `nil` to resolve as a delete.\n\nExample:\n```\n\"custom_conflict_resolver\":\\`\n\tfunction(conflict) {\n\t\tconsole.log(\"Doc ID: \"+conflict.LocalDocument._id);\n\t\tconsole.log(\"Full remote doc: \"+JSON.stringify(conflict.RemoteDocument));\n\t\treturn conflict.RemoteDocument;\n\t}\n\\`\n```\n\nUsing complex `custom_conflict_resolver` functions can noticeably degrade performance. Use a built-in resolver whenever possible.\n\nThis is an Enterprise Edition only feature.\n"
+      description: "This specifies the Javascript function to use to resolve conflicts between conflicting revisions.\n \nThis **must** be used when `conflict_resolution_type=custom`. This property will be ignored when `conflict_resolution_type` is not `custom`.\n\nThe Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties:\n* `LocalDocument` - The local document. This contains the document ID under the `_id` key.\n* `RemoteDocument` - The remote document\nThe function should return the new document's body. This can be the winning revision (for example, `return conflict.LocalDocument`), a new body, or `nil` to resolve as a delete.\n\nExample:\n```\n\"custom_conflict_resolver\":\\`\n\tfunction(conflict) {\n\t\tconsole.log(\"Doc ID: \"+conflict.LocalDocument._id);\n\t\tconsole.log(\"Full remote doc: \"+JSON.stringify(conflict.RemoteDocument));\n\t\treturn conflict.RemoteDocument;\n\t}\n\\`\n```\n\nUsing complex `custom_conflict_resolver` functions can noticeably degrade performance. Use a built-in resolver whenever possible.\n\nThis is an Enterprise Edition only feature.\n"
       type: string
       default: none
     purge_on_removal:

docs/api/paths/admin/db-_compact.yaml

@@ -25,7 +25,7 @@ post:
     - $ref: ../../components/parameters.yaml#/compact-type
     - name: action
       in: query
-      description: Defines whether the a compact operation is being started or stopped.
+      description: Defines whether the compact operation is being started or stopped.
       schema:
         type: string
         default: start

docs/api/paths/admin/db-_ensure_full_commit.yaml

@@ -8,7 +8,7 @@
 parameters:
   - $ref: ../../components/parameters.yaml#/db
 post:
-  summary: '/{db}/_ensure_full_commit'
+  summary: Ensure Full Commit
   description: |-
     This endpoint is non-functional but is present for CouchDB compatibility.
 

docs/api/paths/admin/db-_replication-.yaml

@@ -53,17 +53,3 @@ post:
   tags:
     - Replication
   operationId: post_db-_replication-
-head:
-  summary: /{db}/_replication/
-  responses:
-    '200':
-      description: OK
-    '404':
-      description: Not Found
-  tags:
-    - Replication
-  description: |-
-    Required Sync Gateway RBAC roles:
-
-    * Sync Gateway Replicator
-  operationId: head_db-_replication-

docs/api/paths/admin/db-_replicationStatus-.yaml

@@ -34,17 +34,3 @@ get:
   tags:
     - Replication
   operationId: get_db-_replicationStatus-
-head:
-  summary: /{db}/_replicationStatus/
-  responses:
-    '200':
-      description: OK
-    '400':
-      description: Bad Request
-  tags:
-    - Replication
-  description: |-
-    Required Sync Gateway RBAC roles:
-
-    * Sync Gateway Replicator
-  operationId: head_db-_replicationStatus-

docs/api/paths/admin/db-_session.yaml

@@ -72,13 +72,3 @@ post:
   tags:
     - Session
   operationId: post_db-_session
-head:
-  summary: /{db}/_session
-  responses:
-    '200':
-      description: OK
-    '404':
-      $ref: ../../components/responses.yaml#/Not-found
-  tags:
-    - Session
-  operationId: head_db-_session

docs/api/paths/admin/db-_user-.yaml

@@ -59,19 +59,3 @@ post:
   tags:
     - Database Security
   operationId: post_db-_user-
-head:
-  summary: /{db}/_user/
-  responses:
-    '200':
-      description: OK
-    '404':
-      $ref: ../../components/responses.yaml#/Not-found
-  tags:
-    - Database Security
-  description: |-
-    Required Sync Gateway RBAC roles:
-
-    * Sync Gateway Architect
-    * Sync Gateway Application
-    * Sync Gateway Application Read Only
-  operationId: head_db-_user-

docs/api/paths/admin/keyspace-_all_docs.yaml

@@ -77,30 +77,3 @@ post:
   tags:
     - Document
   operationId: post_keyspace-_all_docs
-head:
-  summary: /{db}/_all_docs
-  responses:
-    '200':
-      description: OK
-    '400':
-      $ref: ../../components/responses.yaml#/request-problem
-    '404':
-      $ref: ../../components/responses.yaml#/Not-found
-  tags:
-    - Document
-  parameters:
-    - $ref: ../../components/parameters.yaml#/include_docs
-    - $ref: ../../components/parameters.yaml#/Include-channels
-    - $ref: ../../components/parameters.yaml#/include-access
-    - $ref: ../../components/parameters.yaml#/include-revs
-    - $ref: ../../components/parameters.yaml#/include-seqs
-    - $ref: ../../components/parameters.yaml#/keys
-    - $ref: ../../components/parameters.yaml#/startkey
-    - $ref: ../../components/parameters.yaml#/endkey
-    - $ref: ../../components/parameters.yaml#/limit-result-rows
-  description: |-
-    Required Sync Gateway RBAC roles:
-
-    * Sync Gateway Application
-    * Sync Gateway Application Read Only
-  operationId: head_keyspace-_all_docs

docs/api/paths/admin/keyspace-_changes.yaml

@@ -176,20 +176,3 @@ post:
   tags:
     - Database Management
   operationId: post_keyspace-_changes
-head:
-  summary: /{db}/_changes
-  responses:
-    '200':
-      description: OK
-    '400':
-      description: Bad Request
-    '404':
-      description: Not Found
-  tags:
-    - Database Management
-  description: |-
-    Required Sync Gateway RBAC roles:
-
-    * Sync Gateway Application
-    * Sync Gateway Application Read Only
-  operationId: head_keyspace-_changes

docs/api/paths/admin/keyspace-_raw-docid.yaml

@@ -11,7 +11,7 @@ parameters:
 get:
   summary: Get a document with the corresponding metadata
   description: |-
-    Returns the a documents latest revision with its metadata.
+    Returns a document's latest revision with its metadata.
 
     Note: The direct use of this endpoint is unsupported. The sync metadata is maintained internally by Sync Gateway and its structure can change. It should not be used to drive business logic of applications since the response to the `/{db}/_raw/{id}` endpoint can change at any time.
 
@@ -23,7 +23,7 @@ get:
     - $ref: ../../components/parameters.yaml#/include_doc
     - name: redact
       in: query
-      description: This redacts sensitive parts of the response. Cannot be used when `include_docs=true`
+      description: This redacts sensitive parts of the response. Cannot be used when `include_doc=true`
       schema:
         type: boolean
   responses:
@@ -72,7 +72,7 @@ get:
                     description: The document CAS (Concurrent Document Mutations) number used for document locking.
                     type: string
                   value_crc32c:
-                    description: The documents CRC32 number.
+                    description: The document's CRC32 number.
                     type: string
                   channel_set:
                     description: The channels the document has been in.
@@ -112,20 +112,3 @@ get:
   tags:
     - Document
   operationId: get_keyspace-_raw-docid
-head:
-  summary: /{keyspace}/_raw/{docid}
-  responses:
-    '200':
-      description: Document exists
-    '400':
-      $ref: ../../components/responses.yaml#/request-problem
-    '404':
-      $ref: ../../components/responses.yaml#/Not-found
-  tags:
-    - Document
-  description: |-
-    Required Sync Gateway RBAC roles:
-
-    * Sync Gateway Application
-    * Sync Gateway Application Read Only
-  operationId: head_keyspace-_raw-docid

docs/api/paths/common/_ping.yaml

@@ -19,12 +19,3 @@ get:
   tags:
     - Server
   operationId: get__ping
-head:
-  responses:
-    '200':
-      description: Server is available
-  tags:
-    - Server
-  summary: Check if API is available
-  description: Returns OK status if API is available.
-  operationId: head__ping

docs/api/paths/public/db-_ensure_full_commit.yaml

@@ -8,7 +8,7 @@
 parameters:
   - $ref: ../../components/parameters.yaml#/db
 post:
-  summary: '/{db}/_ensure_full_commit'
+  summary: Ensure Full Commit
   description: This endpoint is non-functional but is present for CouchDB compatibility.
   responses:
     '201':

docs/api/paths/public/db-_session.yaml

@@ -114,13 +114,3 @@ delete:
   tags:
     - Session
   operationId: delete_db-_session
-head:
-  summary: /{db}/_session
-  responses:
-    '200':
-      description: OK
-    '404':
-      $ref: ../../components/responses.yaml#/Not-found
-  tags:
-    - Session
-  operationId: head_db-_session

docs/api/paths/public/keyspace-_all_docs.yaml

@@ -65,26 +65,3 @@ post:
   tags:
     - Document
   operationId: post_keyspace-_all_docs
-head:
-  summary: /{db}/_all_docs
-  responses:
-    '200':
-      description: OK
-    '400':
-      $ref: ../../components/responses.yaml#/request-problem
-    '404':
-      $ref: ../../components/responses.yaml#/Not-found
-  tags:
-    - Document
-  parameters:
-    - $ref: ../../components/parameters.yaml#/include_docs
-    - $ref: ../../components/parameters.yaml#/Include-channels
-    - $ref: ../../components/parameters.yaml#/include-access
-    - $ref: ../../components/parameters.yaml#/include-revs
-    - $ref: ../../components/parameters.yaml#/include-seqs
-    - $ref: ../../components/parameters.yaml#/keys
-    - $ref: ../../components/parameters.yaml#/startkey
-    - $ref: ../../components/parameters.yaml#/endkey
-    - $ref: ../../components/parameters.yaml#/limit-result-rows
-  description: ''
-  operationId: head_keyspace-_all_docs

docs/api/paths/public/keyspace-_changes.yaml

@@ -156,16 +156,3 @@ post:
   tags:
     - Database Management
   operationId: post_keyspace-_changes
-head:
-  summary: /{db}/_changes
-  responses:
-    '200':
-      description: OK
-    '400':
-      description: Bad Request
-    '404':
-      description: Not Found
-  tags:
-    - Database Management
-  description: ''
-  operationId: head_keyspace-_changes