From a72337e9af2d4294eef53552b0f7750ca0d3e203 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Tue, 11 Aug 2026 10:19:39 -0400 Subject: [PATCH 1/3] docs(api): fix OpenAPI type/schema mismatches and rewrite backtick sanitization test MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix number/string schema types - number→integer (number is float) - boolean fields wrongly typed string - Fix `doc_write_conflicts`→`doc_write_conflict` field name typo - Fix `javascript_timeout_secs` default (60→0) and stats log `max_age` default (6→90) to match code - Replace minimum/maximum with minLength/maxLength for string-length constraints - Fix `revs_limit` minimum (0→1) and stats logging description ("Trace"→"Stats" logging, copy-paste fix) - Add `x-enumDescriptions` for enum params/schemas lacking them - Add `oneOf: [integer, string]` for changes-feed `seq` to reflect compound sequence values --- docs/api/components/parameters.yaml | 14 +- docs/api/components/responses.yaml | 4 +- docs/api/components/schemas.yaml | 133 +++++++++++------- .../api/paths/admin/_profile-profilename.yaml | 6 + docs/api/paths/admin/_sgcollect_info.yaml | 3 + docs/api/paths/admin/db-.yaml | 4 +- .../db-_replicationStatus-replicationid.yaml | 4 + docs/api/paths/admin/keyspace-_changes.yaml | 11 ++ .../admin/keyspace-_dumpchannel-channel.yaml | 4 +- .../paths/admin/keyspace-docid-attach.yaml | 4 +- docs/api/paths/diagnostic/keyspace-sync.yaml | 4 +- docs/api/paths/public/db-.yaml | 4 +- docs/api/paths/public/keyspace-_changes.yaml | 11 ++ .../paths/public/keyspace-docid-attach.yaml | 4 +- 14 files changed, 141 insertions(+), 69 deletions(-) diff --git a/docs/api/components/parameters.yaml b/docs/api/components/parameters.yaml index 01bcb7bf43..4b73852a9c 100644 --- a/docs/api/components/parameters.yaml +++ b/docs/api/components/parameters.yaml @@ -52,6 +52,9 @@ compact-type: enum: - attachment - tombstone + x-enumDescriptions: + attachment: Clean up legacy (pre-3.0) attachments. + tombstone: Purge the JSON bodies of old, non-current revisions. description: |- This is the type of compaction to use. The type must be either: * `attachment` for cleaning up legacy (pre-3.0) attachments @@ -168,7 +171,7 @@ include_doc: in: query required: false schema: - type: string + type: boolean description: Include the body associated with the document. include_docs: name: include_docs @@ -199,7 +202,7 @@ limit-result-rows: in: query required: false schema: - type: number + type: integer description: This limits the number of result rows returned. Using a value of `0` has the same effect as the value `1`. log-level: name: logLevel @@ -241,7 +244,7 @@ offline: in: query required: false schema: - type: string + type: boolean description: 'If true, the OpenID Connect provider is requested to confirm with the user the permissions requested and refresh the OIDC token. To do this, access_type=offline and prompt=consent is set on the redirection link.' oidc-code: name: code @@ -331,8 +334,8 @@ replicationid: required: true schema: type: string - minimum: 1 - maximum: 160 + minLength: 1 + maxLength: 160 description: What replication to target based on its replication ID. replicator2: name: replicator2 @@ -494,6 +497,7 @@ stale: enum: - ok - update_after + - "false" key: name: key in: query diff --git a/docs/api/components/responses.yaml b/docs/api/components/responses.yaml index 1c039d832d..0d8f5983ba 100644 --- a/docs/api/components/responses.yaml +++ b/docs/api/components/responses.yaml @@ -157,9 +157,9 @@ all-docs: type: string uniqueItems: true total_rows: - type: number + type: integer update_seq: - type: number + type: integer required: - rows - total_rows diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 274c9c7729..09eb5fab6e 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -408,7 +408,7 @@ User-session-information: type: object additionalProperties: x-additionalPropertiesName: channelName - type: number + type: integer minimum: 1 description: The sequence number the user was granted access. title: sequence number @@ -450,7 +450,7 @@ OIDC-callback: type: string expires_in: description: The time until the id_token expires (TTL). - type: number + type: integer title: OpenID Connect callback properties OIDC-token: description: Properties expected back from an OpenID Connect provider after successful authentication @@ -523,7 +523,7 @@ Document: properties: start: description: Prefix number for the latest revision. - type: number + type: integer ids: description: 'Array of valid Revision Tree IDs, in reverse order (latest first).' type: array @@ -575,8 +575,10 @@ Changes-feed: type: object properties: seq: - description: The change sequence number. - type: number + description: The change sequence number. This is usually a plain integer, but can be a compound (string) sequence value in some cases, such as during a channel backfill. + oneOf: + - type: integer + - type: string id: description: The document ID the change happened on. type: string @@ -882,7 +884,7 @@ Replication: When the replication ID is specified in the URL, this must be set to the same replication ID if specifying it at all. type: string - maximum: 160 + maxLength: 160 run_as: description: This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to. type: string @@ -950,7 +952,7 @@ Replication-status: doc_write_failures: description: The number of documents that have failed to be wrote (pushed) to the target database. There will be no attempt to try to push these docs again. type: integer - doc_write_conflicts: + doc_write_conflict: description: The number of documents that had a conflict. type: integer rejected_by_remote: @@ -1024,7 +1026,7 @@ Database: default: The database name bucket_op_timeout_ms: description: 'This is the amount of milliseconds should pass before a bucket operation times out. An error will be returned if the bucket operation times out saying: `operation timed out`.' - type: number + type: integer cacertpath: description: The root CA cert path for X.509 bucket authentication. type: string @@ -1073,11 +1075,11 @@ Database: default: 50000 max_wait_pending: description: The maximum time (in milliseconds) for waiting for a pending sequence before skipping it. - type: number + type: integer default: 5000 max_wait_skipped: description: The maximum amount of time (in milliseconds) to wait for a skipped sequence before abandoning it. - type: number + type: integer default: 3600000 min_length: description: The minimum number of entries to maintain in the cache per channel. @@ -1139,7 +1141,7 @@ Database: **Deprecated, please use the database setting `cache.channel_cache.max_length` instead** The maximum number of entries maintained in cache per channel. - type: number + type: integer deprecated: true channel_cache_min_length: description: |- @@ -1167,14 +1169,14 @@ Database: **Deprecated, please use the database setting `cache.channel_cache.max_wait_pending` instead** The maximum time (in milliseconds) for waiting for a pending sequence before skipping it. - type: number + type: integer deprecated: true max_wait_skipped: description: |- **Deprecated, please use the database setting `cache.channel_cache.max_wait_skipped` instead** The maximum time (in milliseconds) for waiting for pending sequences before skipping. - type: number + type: integer deprecated: true certpath: description: The cert path (public key) for X.509 bucket auth. @@ -1224,7 +1226,7 @@ Database: The number of seconds deltas for old revisions are available for. This defaults to 24 hours (in seconds). - type: number + type: integer default: 86400 disable_password_auth: description: Whether to disable username/password authentication and only allow OIDC and guest access. @@ -1261,7 +1263,7 @@ Database: default: false max_processes: description: The maximum amount of concurrent event handling independent functions that can be running at the same time. - type: string + type: integer wait_for_process: description: The maximum amount of time (in milliseconds) to wait when the even queue is full. type: string @@ -1297,7 +1299,7 @@ Database: Partitions are distributed among all Sync Gateway nodes participating in import processing (`import_docs=true`), and each process a subset of the server's vbuckets. Each partition is processed by an independent function that runs simultaneously to others, so `import_partitions` can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node. - type: number + type: integer default: 16 minimum: 1 maximum: 1024 @@ -1308,12 +1310,12 @@ Database: $ref: '#/NumIndexPartitions' num_replicas: description: This is the number of Global Secondary Indexes (GSI) to use for core indexes. - type: number + type: integer default: 1 javascript_timeout_secs: description: The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped. - type: number - default: 60 + type: integer + default: 0 keypath: description: The key path (private key) for X.509 bucket auth type: string @@ -1454,7 +1456,7 @@ Database: description: List of enabled audit events for this database. type: array items: - type: number + type: integer example: [1234, 5678] console: description: Console logging configuration. @@ -1582,7 +1584,7 @@ Database: type: string old_rev_expiry_seconds: description: The number of seconds before old revisions are removed from the Couchbase Server bucket. - type: number + type: integer default: 300 password: description: The password for authenticating to the server. @@ -1599,9 +1601,9 @@ Database: revs_limit: description: |- The maximum depth a document's revision tree can grow to. - type: number + type: integer default: 50 - minimum: 0 + minimum: 1 roles: additionalProperties: x-additionalPropertiesName: rolename @@ -1659,7 +1661,7 @@ Database: default: 300 slow_query_warning_threshold: description: 'The amount of milliseconds a N1QL query should run before logging a warning. ' - type: number + type: integer default: 500 store_legacy_revtree_data: description: |- @@ -1690,7 +1692,7 @@ Database: type: boolean dcp_read_buffer: description: Set the dcp feed to use a different read buffer size. - type: number + type: integer force_api_forbidden_errors: description: Force REST API errors to return forbidden type: boolean @@ -1699,7 +1701,7 @@ Database: type: boolean kv_buffer: description: Set the kv pool to use a different buffer size. - type: number + type: integer oidc_test_provider: type: object properties: @@ -1727,6 +1729,11 @@ Database: - "Lax" - "None" - "Strict" + x-enumDescriptions: + Default: Omit the SameSite attribute entirely. + Lax: Blocked on cross-site requests, but allowed when a user navigates to the site directly. + None: Allowed on all requests, including cross-site. Requires the cookie to be marked `Secure`. + Strict: Only sent on same-site requests. sgr_tls_skip_verify: description: Enable self-signed certificates for SG-replicate testing. type: boolean @@ -1741,19 +1748,19 @@ Database: properties: access_and_role_grants_per_doc: description: The number of access and role grants per document to be used as a threshold for grant count warnings. - type: number + type: integer channel_name_size: description: The number of channel name characters to be used as a threshold for channel name warnings. - type: number + type: integer channels_per_doc: description: The number of channels per document to be used as a threshold for the channel count warnings. - type: number + type: integer channels_per_user: description: The number of channels per user to be used as a threshold for channel count warnings. - type: number + type: integer xattr_size_bytes: description: The number of bytes to be used as a threshold for xattr size limit warnings. - type: number + type: integer use_views: description: Force the use of views instead of GSI. type: boolean @@ -1764,7 +1771,7 @@ Database: This is an Enterprise Edition feature only. type: string - maximum: 15 + maxLength: 15 username: description: The username for authenticating to the server. type: string @@ -1806,7 +1813,7 @@ Database: description: |- **Deprecated, please use the database setting `index.num_replicas` instead** deprecated: true - type: number + type: integer default: 1 pool: description: This field is unsupported and ignored. @@ -1818,7 +1825,7 @@ Database: **Deprecated, please use the database setting `cache.rev_cache.size` instead** The maximum number of revisions to store in the revision cache. - type: number + type: integer deprecated: true suspendable: description: This option has no effect. @@ -1981,7 +1988,7 @@ Event-config: type: string timeout: description: The amount of time (in seconds) to attempt connect to the webhook before giving up. - type: number + type: integer title: Event-config Resync-status: description: The status of a resync operation @@ -1996,6 +2003,12 @@ Resync-status: - stopping - stopped - error + x-enumDescriptions: + running: Currently running. + completed: Finished successfully. + stopping: In the process of stopping. + stopped: Stopped before completion. + error: Failed with an error. start_time: description: The ISO-8601 date and time the resync operation was started. type: string @@ -2038,6 +2051,12 @@ Attachment-Migration-status: - stopping - stopped - error + x-enumDescriptions: + running: Currently running. + completed: Finished successfully. + stopping: In the process of stopping. + stopped: Stopped before completion. + error: Failed with an error. start_time: description: The ISO-8601 date and time the attachment migration operation was started. type: string @@ -2076,6 +2095,12 @@ Metadata-Migration-status: - stopping - stopped - error + x-enumDescriptions: + running: Currently running. + completed: Finished successfully. + stopping: In the process of stopping. + stopped: Stopped before completion. + error: Failed with an error. start_time: description: The ISO-8601 date and time the metadata migration operation was started. type: string @@ -2132,19 +2157,19 @@ Compact-status: **Applicable to tombstone compaction only** This is the amount of documents that have been purged so far. - type: string + type: integer marked_attachments: description: |- **Applicable to attachment compaction only** This is the number of references there are to legacy attachments. - type: string + type: integer purged_attachments: description: |- **Applicable to attachment compaction only** This is the amount of attachments that have been purged so far. - type: string + type: integer compact_id: description: |- **Applicable to attachment compaction only** @@ -2159,14 +2184,18 @@ Compact-status: For failed processes, this indicates the phase at which a compact_id restart will commence (where relevant). type: string - dry_run: - description: | - **Applicable to attachment compaction only** - type: string enum: - mark - sweep - cleanup + x-enumDescriptions: + mark: Scanning documents to find attachments still in use. + sweep: Deleting attachments that are no longer used. + cleanup: Finishing up and clearing temporary compaction data. + dry_run: + description: | + **Applicable to attachment compaction only** + type: boolean required: - status - start_time @@ -2231,7 +2260,7 @@ Startup-config: default: 90s max_connections: description: Max of incoming HTTP connections to accept - type: number + type: integer default: 0 metrics_interface: description: |- @@ -2404,7 +2433,7 @@ Startup-config: - $ref: '#/Logging-config' max_file_descriptors: description: Max of open file descriptors (RLIMIT_NOFILE) - type: number + type: integer default: 5000 minimum: 0 readOnly: true @@ -2513,6 +2542,11 @@ Logging-config: - partial - full - unset + x-enumDescriptions: + none: No redaction; logs may contain sensitive data. + partial: Redacts sensitive data from logs. Default. + full: Not implemented separately; behaves the same as `partial`. + unset: Not explicitly configured; behaves the same as `partial`. readOnly: true console: allOf: @@ -2719,7 +2753,7 @@ Logging-config: readOnly: true stats: type: object - description: Trace logging configuration. + description: Stats logging configuration. properties: enabled: description: Toggle for this log output @@ -2750,7 +2784,7 @@ Logging-config: default: "" max_age: description: The maximum number of days to retain old log files. - default: 6 + default: 90 type: integer collation_buffer_size: description: The size of the log collation buffer @@ -2810,7 +2844,7 @@ Audit-logging-config: description: List of enabled global audit events. type: array items: - type: number + type: integer example: [1234, 5678] readOnly: true Console-logging-keys-level: @@ -2985,7 +3019,7 @@ Status: properties: seq: description: The latest sequence number in the database. - type: number + type: integer minimum: 0 server_uuid: description: The server unique identifier. @@ -3072,7 +3106,6 @@ Status: (cgroupv2 `memory.max` or cgroupv1 `memory.limit_in_bytes`). Only present when running inside a cgroup with a memory limit configured. type: integer - format: uint64 example: 2147483648 node_uid: description: |- @@ -3298,7 +3331,7 @@ NumIndexPartitions: The number of partitions to use for the large indexes created by Sync Gateway. It is not recommended to set this unless you require additional horizontal scalability for individual indexes and have appropriately scaled your Query nodes to handle the increased query parallelism. If set, the recommended number is 8 and does not need to be directly related to the number of your Query nodes. Ensure documentation is read to understand the performance tradeoffs and instructions for migration if you have previously run with only one partition. See [/{db}/_index_init](#operation/post_db-_index_init) for more information. If not specified or 1, all indexes will be non partitioned. - type: number + type: integer default: 1 title: Number of Index Partitions IndexSettings: diff --git a/docs/api/paths/admin/_profile-profilename.yaml b/docs/api/paths/admin/_profile-profilename.yaml index a2a9faa349..d97a21ab2d 100644 --- a/docs/api/paths/admin/_profile-profilename.yaml +++ b/docs/api/paths/admin/_profile-profilename.yaml @@ -18,6 +18,12 @@ parameters: - threadcreate - mutex - goroutine + x-enumDescriptions: + heap: A snapshot of memory usage, useful for spotting memory leaks. + block: Where the server is waiting on locks or channels. + threadcreate: Where new OS threads were created. + mutex: Where goroutines are contending for the same lock. + goroutine: A snapshot of everything the server is currently doing. post: summary: Create point-in-time profile description: |- diff --git a/docs/api/paths/admin/_sgcollect_info.yaml b/docs/api/paths/admin/_sgcollect_info.yaml index 0f451e2c64..dbf4e26dac 100644 --- a/docs/api/paths/admin/_sgcollect_info.yaml +++ b/docs/api/paths/admin/_sgcollect_info.yaml @@ -54,6 +54,9 @@ post: enum: - partial - none + x-enumDescriptions: + partial: Redacts sensitive data from the collected logs. Default. + none: No redaction; collected logs may contain sensitive data. redact_salt: description: The salt to use for the log redactions. type: string diff --git a/docs/api/paths/admin/db-.yaml b/docs/api/paths/admin/db-.yaml index 2879bda76e..181454875d 100644 --- a/docs/api/paths/admin/db-.yaml +++ b/docs/api/paths/admin/db-.yaml @@ -50,11 +50,11 @@ get: type: boolean purge_seq: description: Unused field. - type: number + type: integer default: 0 disk_format_version: description: Unused field. - type: number + type: integer default: 0 state: allOf: # use allOf to prevent DatabaseState from showing as the type in the display diff --git a/docs/api/paths/admin/db-_replicationStatus-replicationid.yaml b/docs/api/paths/admin/db-_replicationStatus-replicationid.yaml index e4ca31bd19..ed0f93dfe8 100644 --- a/docs/api/paths/admin/db-_replicationStatus-replicationid.yaml +++ b/docs/api/paths/admin/db-_replicationStatus-replicationid.yaml @@ -63,6 +63,10 @@ put: - start - stop - reset + x-enumDescriptions: + start: Start a stopped replication. + stop: Stop an active replication. + reset: Reset replication checkpoints. The replication must be stopped first. responses: '200': description: Successfully changed target state of replicator diff --git a/docs/api/paths/admin/keyspace-_changes.yaml b/docs/api/paths/admin/keyspace-_changes.yaml index 1c83da3606..e49e072a00 100644 --- a/docs/api/paths/admin/keyspace-_changes.yaml +++ b/docs/api/paths/admin/keyspace-_changes.yaml @@ -38,6 +38,9 @@ get: enum: - main_only - all_docs + x-enumDescriptions: + main_only: Return only the current winning revision. + all_docs: Return all leaf revisions, including conflicts and deleted conflicts. - name: active_only in: query description: Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. @@ -58,6 +61,9 @@ get: enum: - sync_gateway/bychannel - _doc_ids + x-enumDescriptions: + sync_gateway/bychannel: Filter by channel, using the `channels` parameter. + _doc_ids: Filter by document ID, using the `doc_ids` parameter. Requires `feed=normal`. - name: channels in: query description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.' @@ -95,6 +101,11 @@ get: - longpoll - continuous - websocket + x-enumDescriptions: + normal: Return all current changes at once, then close the connection. + longpoll: Return current changes, then hold the connection open to wait for more before responding again. + continuous: Stream each change as it happens, over a single long-lived connection. + websocket: Stream changes over a WebSocket connection. - name: request_plus in: query diff --git a/docs/api/paths/admin/keyspace-_dumpchannel-channel.yaml b/docs/api/paths/admin/keyspace-_dumpchannel-channel.yaml index 1dd6d3079d..a19af56145 100644 --- a/docs/api/paths/admin/keyspace-_dumpchannel-channel.yaml +++ b/docs/api/paths/admin/keyspace-_dumpchannel-channel.yaml @@ -27,9 +27,9 @@ get: parameters: - name: since in: query - description: Starts the results from the change immediately after the given sequence ID. Sequence IDs should be considered opaque; they come from the last_seq property of a prior response. + description: Starts the results from the change immediately after the given sequence number. schema: - type: string + type: integer responses: '200': description: Successfully got all documents in the channel diff --git a/docs/api/paths/admin/keyspace-docid-attach.yaml b/docs/api/paths/admin/keyspace-docid-attach.yaml index e3f68aa9d8..58b9372f61 100644 --- a/docs/api/paths/admin/keyspace-docid-attach.yaml +++ b/docs/api/paths/admin/keyspace-docid-attach.yaml @@ -53,7 +53,7 @@ get: headers: Content-Length: schema: - type: number + type: integer description: Length of the attachment in bytes Etag: schema: @@ -135,7 +135,7 @@ head: Content-Length: schema: description: Length of the attachment in bytes - type: number + type: integer Etag: schema: type: string diff --git a/docs/api/paths/diagnostic/keyspace-sync.yaml b/docs/api/paths/diagnostic/keyspace-sync.yaml index ef8fa03420..8d36c3dc50 100644 --- a/docs/api/paths/diagnostic/keyspace-sync.yaml +++ b/docs/api/paths/diagnostic/keyspace-sync.yaml @@ -86,7 +86,7 @@ post: - type: string example: foo description: A string value to be used as the user XATTR. - - type: integer + - type: number example: 100 description: A number value to be used as the user XATTR. - type: boolean @@ -163,7 +163,7 @@ post: example: channel1 expiry: description: The document expiry (TTL in seconds) as determined by the sync function. - type: number + type: integer example: 300 exception: $ref: ../../components/schemas.yaml#/DiagnosticFunctionException diff --git a/docs/api/paths/public/db-.yaml b/docs/api/paths/public/db-.yaml index a7feb6366e..f6682ee2cc 100644 --- a/docs/api/paths/public/db-.yaml +++ b/docs/api/paths/public/db-.yaml @@ -45,11 +45,11 @@ get: type: boolean purge_seq: description: Unused field. - type: number + type: integer default: 0 disk_format_version: description: Unused field. - type: number + type: integer default: 0 state: allOf: # use allOf to prevent DatabaseState from showing as the type in the display diff --git a/docs/api/paths/public/keyspace-_changes.yaml b/docs/api/paths/public/keyspace-_changes.yaml index 6a1a348f9d..752d20a0be 100644 --- a/docs/api/paths/public/keyspace-_changes.yaml +++ b/docs/api/paths/public/keyspace-_changes.yaml @@ -33,6 +33,9 @@ get: enum: - main_only - all_docs + x-enumDescriptions: + main_only: Return only the current winning revision. + all_docs: Return all leaf revisions, including conflicts and deleted conflicts. - name: active_only in: query description: Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. @@ -53,6 +56,9 @@ get: enum: - sync_gateway/bychannel - _doc_ids + x-enumDescriptions: + sync_gateway/bychannel: Filter by channel, using the `channels` parameter. + _doc_ids: Filter by document ID, using the `doc_ids` parameter. Requires `feed=normal`. - name: channels in: query description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.' @@ -90,6 +96,11 @@ get: - longpoll - continuous - websocket + x-enumDescriptions: + normal: Return all current changes at once, then close the connection. + longpoll: Return current changes, then hold the connection open to wait for more before responding again. + continuous: Stream each change as it happens, over a single long-lived connection. + websocket: Stream changes over a WebSocket connection. - name: version_type in: query description: 'The preferred type of document versioning to use for the changes feed.' diff --git a/docs/api/paths/public/keyspace-docid-attach.yaml b/docs/api/paths/public/keyspace-docid-attach.yaml index bab8400882..2e8671026d 100644 --- a/docs/api/paths/public/keyspace-docid-attach.yaml +++ b/docs/api/paths/public/keyspace-docid-attach.yaml @@ -48,7 +48,7 @@ get: headers: Content-Length: schema: - type: number + type: integer description: Length of the attachment in bytes Etag: schema: @@ -122,7 +122,7 @@ head: Content-Length: schema: description: Length of the attachment in bytes - type: number + type: integer Etag: schema: type: string From 3254ff5ce1cac38fb85b4ffba0350f284861a867 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Tue, 11 Aug 2026 11:50:05 -0400 Subject: [PATCH 2/3] fix up from droid --- docs/api/components/schemas.yaml | 5 ++- docs/api/paths/admin/keyspace-_changes.yaml | 35 ++++++++++++-------- docs/api/paths/public/keyspace-_changes.yaml | 33 ++++++++++-------- 3 files changed, 45 insertions(+), 28 deletions(-) diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 09eb5fab6e..bd264f6021 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -463,7 +463,8 @@ OIDC-token: refresh_token: type: string expires_in: - type: string + type: integer + minimum: 0 id_token: type: string title: OIDC-token @@ -3106,6 +3107,8 @@ Status: (cgroupv2 `memory.max` or cgroupv1 `memory.limit_in_bytes`). Only present when running inside a cgroup with a memory limit configured. type: integer + format: int64 + minimum: 0 example: 2147483648 node_uid: description: |- diff --git a/docs/api/paths/admin/keyspace-_changes.yaml b/docs/api/paths/admin/keyspace-_changes.yaml index e49e072a00..56c0ac551c 100644 --- a/docs/api/paths/admin/keyspace-_changes.yaml +++ b/docs/api/paths/admin/keyspace-_changes.yaml @@ -66,16 +66,21 @@ get: _doc_ids: Filter by document ID, using the `doc_ids` parameter. Requires `feed=normal`. - name: channels in: query - description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.' + description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannel`.' schema: type: string - name: doc_ids in: query - description: 'A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`. Also accepts a comma separated list of document IDs instead.' + description: 'A JSON array of document IDs, serialized to a string, to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`. Also accepts a comma-separated list of document IDs instead.' schema: - type: array - items: - type: string + type: string + examples: + jsonArray: + summary: Serialized JSON array + value: '["doc1","doc2"]' + commaSeparated: + summary: Comma-separated list + value: 'doc1,doc2' - name: heartbeat in: query description: The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to `feed=longpoll` or `feed=continuous`. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration. If heartbeat is non zero, it must be at least 25000 milliseconds. @@ -156,34 +161,36 @@ post: properties: limit: description: Maximum number of changes to return. - type: string + type: integer style: description: Controls whether to return the current winning revision (`main_only`) or all the leaf revision including conflicts and deleted former conflicts (`all_docs`). type: string active_only: description: Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. - type: string + type: boolean include_docs: description: Include the body associated with each document. - type: string + type: boolean revocations: description: 'If true, revocation messages will be sent on the changes feed.' - type: string + type: boolean filter: description: Set a filter to either filter by channels or document IDs. type: string channels: - description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.' + description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannel`.' type: string doc_ids: - description: 'A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`.' - type: string + description: 'A JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`.' + type: array + items: + type: string heartbeat: description: The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to `feed=longpoll` or `feed=continuous`. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration. - type: string + type: integer timeout: description: 'This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for `feed=longpoll` or `feed=continuous` changes feeds. Setting to 0 results in no timeout.' - type: string + type: integer feed: description: 'The type of changes feed to use. ' type: string diff --git a/docs/api/paths/public/keyspace-_changes.yaml b/docs/api/paths/public/keyspace-_changes.yaml index 752d20a0be..5319b2a9b3 100644 --- a/docs/api/paths/public/keyspace-_changes.yaml +++ b/docs/api/paths/public/keyspace-_changes.yaml @@ -61,16 +61,21 @@ get: _doc_ids: Filter by document ID, using the `doc_ids` parameter. Requires `feed=normal`. - name: channels in: query - description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.' + description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannel`.' schema: type: string - name: doc_ids in: query - description: 'A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`. Also accepts a comma separated list of document IDs instead.' + description: 'A JSON array of document IDs, serialized to a string, to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`. Also accepts a comma-separated list of document IDs instead.' schema: - type: array - items: - type: string + type: string + examples: + jsonArray: + summary: Serialized JSON array + value: '["doc1","doc2"]' + commaSeparated: + summary: Comma-separated list + value: 'doc1,doc2' - name: heartbeat in: query description: The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to `feed=longpoll` or `feed=continuous`. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration. If heartbeat is non zero, it must be at least 25000 milliseconds. @@ -137,34 +142,36 @@ post: properties: limit: description: Maximum number of changes to return. - type: string + type: integer style: description: Controls whether to return the current winning revision (`main_only`) or all the leaf revision including conflicts and deleted former conflicts (`all_docs`). type: string active_only: description: Set true to exclude deleted documents and notifications for documents the user no longer has access to from the changes feed. - type: string + type: boolean include_docs: description: Include the body associated with each document. type: boolean revocations: description: 'If true, revocation messages will be sent on the changes feed.' - type: string + type: boolean filter: description: Set a filter to either filter by channels or document IDs. type: string channels: - description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannels`.' + description: 'A comma-separated list of channel names to filter the response to only the channels specified. To use this option, the `filter` query option must be set to `sync_gateway/bychannel`.' type: string doc_ids: - description: 'A valid JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`.' - type: string + description: 'A JSON array of document IDs to filter the documents in the response to only the documents specified. To use this option, the `filter` query option must be set to `_doc_ids` and the `feed` parameter must be `normal`.' + type: array + items: + type: string heartbeat: description: The interval (in milliseconds) to send an empty line (CRLF) in the response. This is to help prevent gateways from deciding the socket is idle and therefore closing it. This is only applicable to `feed=longpoll` or `feed=continuous`. This will override any timeouts to keep the feed alive indefinitely. Setting to 0 results in no heartbeat. The maximum heartbeat can be set in the server replication configuration. - type: string + type: integer timeout: description: 'This is the maximum period (in milliseconds) to wait for a change before the response is sent, even if there are no results. This is only applicable for `feed=longpoll` or `feed=continuous` changes feeds. Setting to 0 results in no timeout.' - type: string + type: integer feed: description: 'The type of changes feed to use. ' type: string From 35f5fba1a18ac9601072e8e3f072b0b8d8e5c6a7 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Tue, 11 Aug 2026 11:56:37 -0400 Subject: [PATCH 3/3] fix some serialized json strings --- docs/api/components/parameters.yaml | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/api/components/parameters.yaml b/docs/api/components/parameters.yaml index 4b73852a9c..1157d3d380 100644 --- a/docs/api/components/parameters.yaml +++ b/docs/api/components/parameters.yaml @@ -38,10 +38,9 @@ atts_since: in: query required: false schema: - type: array - items: - type: string - description: Include attachments only since specified revisions. Excludes the attachments for the specified revisions. Only gets used if `attachments=true`. + type: string + example: '["1-abc","2-def"]' + description: 'A serialized JSON array of revision IDs. Include attachments only since the specified revisions, excluding the attachments for the specified revisions. Only gets used if `attachments=true`.' compact-type: name: type in: query @@ -193,10 +192,9 @@ keys: in: query required: false schema: - type: array - items: - type: string - description: An array of document ID strings to filter by. + type: string + example: '["doc1","doc2"]' + description: A serialized JSON array of document ID strings to filter by. limit-result-rows: name: limit in: query @@ -279,10 +277,9 @@ open_revs: in: query required: false schema: - type: array - items: - type: string - description: 'Option to fetch specified revisions of the document. The value can be all to fetch all leaf revisions or an array of revision numbers (i.e. open_revs=["rev1", "rev2"]). Only leaf revision bodies that haven''t been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the `Accept: application/json` request header to get the result as a JSON object.' + type: string + example: '["1-abc","2-def"]' + description: 'Option to fetch specified revisions of the document. The value can be `all` to fetch all leaf revisions, or a serialized JSON array of revision numbers (i.e. `open_revs=["rev1", "rev2"]`). Only leaf revision bodies that haven''t been pruned are guaranteed to be returned. If this option is specified the response will be in multipart format. Use the `Accept: application/json` request header to get the result as a JSON object.' pprof-seconds: name: seconds in: query @@ -357,10 +354,9 @@ revs_from: in: query required: false schema: - type: array - items: - type: string - description: 'Trim the revision history to stop at the first revision in the provided list. If no match is found, the revisions will be trimmed to the `revs_limit`.' + type: string + example: '["1-abc"]' + description: 'Trim the revision history to stop at the first revision in the provided serialized JSON array of revision IDs. If no match is found, the revisions will be trimmed to the `revs_limit`.' revs_limit: name: revs_limit in: query