CBG-5715: type serialized JSON array query parameters as strings

[torcolvin]

CBG-5715

Split out of #8589 — stack 2/9, based on #8649.

atts_since, keys, open_revs, revs_from and _changes?doc_ids are all read as a single query string containing a serialized JSON array — not an OpenAPI array, which renders and validates as repeated/comma-separated query values.

Retype them as string and add examples showing the expected encoding. doc_ids also accepts a comma-separated list, so it gets both examples.

Evidence:

• rest/doc_api.go:54,57 — getJSONStringArrayQuery("revs_from") / ("atts_since")
• rest/bulk_api.go:92 — getJSONStringArrayQuery("keys"); rest/view_api.go:107 JSON-unmarshals keys for views
• rest/doc_api.go:31,145 — open_revs is all or a JSON array string
• rest/changes_api.go:213-228 — GET doc_ids tries JSONUnmarshal first, then falls back to strings.Split(",")

Pre-review checklist

• Logging sensitive data? N/A — docs only
• Updated relevant information in the API specifications in docs/api

🤖 Generated with Claude Code

[factory-droid]

Droid finished @torcolvin's task —— View job

---

Validation complete for PR #8650 (Phase 2).

Summary: No candidate inline comments to validate or post. The OpenAPI parameter schema updates look consistent with the PR description.

[github-actions]

Redocly previews

• Admin API
• Public API
• Metric API
• Diagnostic API

[Copilot]

Pull request overview

Updates the OpenAPI specifications for Sync Gateway’s _changes and related endpoints to correctly document certain query parameters that are serialized JSON arrays carried as a single query-string value, and adds examples to show the expected encoding.

Changes:

• Retypes doc_ids (GET /{keyspace}/_changes) as a string and adds examples for both serialized JSON array and comma-separated formats.
• Retypes shared query parameters (atts_since, keys, open_revs, revs_from) from OpenAPI array to string and adds examples reflecting the serialized-JSON-in-string encoding.
• Updates _changes request body property types (e.g., limit, active_only, heartbeat, timeout) and adds request_plus/version_type documentation in the _changes path specs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/api/paths/public/keyspace-_changes.yaml	Updates public _changes query params (notably doc_ids) and POST body property schemas; adds request_plus and version_type.
docs/api/paths/admin/keyspace-_changes.yaml	Mirrors public _changes spec adjustments for the admin endpoint, including doc_ids query param examples and POST body typing updates.
docs/api/components/parameters.yaml	Retypes JSON-array-in-string query parameters (atts_since, keys, open_revs, revs_from) to string and adds examples/description clarifications.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.