Diagnostic API: Update OpenAPI Specs #7955
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Redocly previews |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the OpenAPI specifications for the Diagnostic API's dry-run endpoints (Sync Function and Import Filter) to align with the desired implementation and improve documentation clarity.
Changes:
- Converted both endpoints from
GETtoPOSTand moveddoc_idfrom query parameter to request body - Added new request properties (
meta,userCtx) to Sync Function API for upcoming user xattrs support and user/channel/role impersonation - Added
expiryresponse property to Sync Function API to document current implementation - Simplified
docschema definition and improved documentation with clearer behavior tables - Introduced shared schemas for common diagnostic API response fields (
DiagnosticFunctionException,DiagnosticFunctionLogging)
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/api/paths/diagnostic/keyspace-sync.yaml | Updated Sync Function dry-run API endpoint: changed HTTP method to POST, moved doc_id to request body, added meta and userCtx request properties, added expiry response property, improved documentation with clearer behavior table and examples |
| docs/api/paths/diagnostic/keyspace-import_filter.yaml | Updated Import Filter dry-run API endpoint: changed HTTP method to POST, moved doc_id to request body, added behavior table similar to Sync Function API, simplified doc schema, switched to shared schema references for exception and logging fields |
| docs/api/components/schemas.yaml | Added two new shared schemas (DiagnosticFunctionException and DiagnosticFunctionLogging) for common diagnostic API response fields |
Comment on lines
+62
to
+86
| properties: | ||
| additionalProperties: | ||
| x-additionalPropertiesName: user_xattr_key | ||
| description: The user XATTR JSON value. The property name must exactly match the configured `user_xattr_key`. The value can be any valid JSON type (Object, String, Number, etc.) | ||
| oneOf: | ||
| - type: object | ||
| additionalProperties: true | ||
| example: | ||
| foo: bar | ||
| description: An object value to be used as the user XATTR. | ||
| - type: string | ||
| example: foo | ||
| description: A string value to be used as the user XATTR. | ||
| - type: integer | ||
| example: 100 | ||
| description: A number value to be used as the user XATTR. | ||
| - type: boolean | ||
| example: true | ||
| description: A boolean value to be used as the user XATTR. | ||
| - type: array | ||
| items: | ||
| example: | ||
| - foo | ||
| - bar | ||
| description: An array of values to be used as the user XATTR. |
There was a problem hiding this comment.
The additionalProperties keyword should not be nested under properties. It should be a sibling to properties at the same level. Move additionalProperties out of the properties block and place it as a direct child of the xattrs object schema.
Suggested change
| properties: | |
| additionalProperties: | |
| x-additionalPropertiesName: user_xattr_key | |
| description: The user XATTR JSON value. The property name must exactly match the configured `user_xattr_key`. The value can be any valid JSON type (Object, String, Number, etc.) | |
| oneOf: | |
| - type: object | |
| additionalProperties: true | |
| example: | |
| foo: bar | |
| description: An object value to be used as the user XATTR. | |
| - type: string | |
| example: foo | |
| description: A string value to be used as the user XATTR. | |
| - type: integer | |
| example: 100 | |
| description: A number value to be used as the user XATTR. | |
| - type: boolean | |
| example: true | |
| description: A boolean value to be used as the user XATTR. | |
| - type: array | |
| items: | |
| example: | |
| - foo | |
| - bar | |
| description: An array of values to be used as the user XATTR. | |
| additionalProperties: | |
| x-additionalPropertiesName: user_xattr_key | |
| description: The user XATTR JSON value. The property name must exactly match the configured `user_xattr_key`. The value can be any valid JSON type (Object, String, Number, etc.) | |
| oneOf: | |
| - type: object | |
| additionalProperties: true | |
| example: | |
| foo: bar | |
| description: An object value to be used as the user XATTR. | |
| - type: string | |
| example: foo | |
| description: A string value to be used as the user XATTR. | |
| - type: integer | |
| example: 100 | |
| description: A number value to be used as the user XATTR. | |
| - type: boolean | |
| example: true | |
| description: A boolean value to be used as the user XATTR. | |
| - type: array | |
| items: | |
| example: | |
| - foo | |
| - bar | |
| description: An array of values to be used as the user XATTR. |
Comment on lines
+83
to
+87
| example: | ||
| - foo | ||
| - bar | ||
| description: An array of values to be used as the user XATTR. | ||
|
|
There was a problem hiding this comment.
The example field for array items should be a single value, not an array. The outer items already indicates this is describing individual array elements. Change the example to a single value like "foo" instead of ["foo", "bar"].
Suggested change
| example: | |
| - foo | |
| - bar | |
| description: An array of values to be used as the user XATTR. | |
| example: foo | |
| description: An array of values to be used as the user XATTR. |
Comment on lines
+17
to
+22
| | `doc` property | `doc_id` property | Behaviour | | ||
| | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Set | Unset | The document body passed will be the `doc` value in the sync function, and `oldDoc` will be empty. | | ||
| | Unset | Set | The document of the given id will be fetched from the bucket/collection and will be passed in as the `doc` value in the sync function. If the document is not found, an error will be returned | | ||
| | Set | Set | The document body passed will be the `doc` value in the sync function, and the `doc_id` will be fetched from the bucket/collection and will be the `oldDoc` value. If `doc_id` doesn't exist, then `oldDoc` will be empty | | ||
| | Unset | Unset | Will throw an error (at least one of `doc` or `doc_id` is required) | |
There was a problem hiding this comment.
The table header alignment is inconsistent. The separator row shows different column widths (----- vs --------) than the actual content requires. Adjust the separator to match the column widths consistently.
6 tasks
6 tasks
RIT3shSapata
pushed a commit
that referenced
this pull request
Jan 21, 2026
RIT3shSapata
pushed a commit
that referenced
this pull request
Jan 21, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Updates to Diagnostic API OpenAPI Specs to align with desired implementation and cleanup.
doc/doc_idtable to description similar to Sync Function APImetarequest property for upcoming user xattrs supportuserCtxrequest property for upcoming user/channel/role impersonation supportexpiryresponse property to document current implementationdocschema to make it obvious it's a user-defined doc body, no metadata required.GETtoPOSTand movedoc_idquery param to request body paramIntegration Tests