fix(openapi): address jtreminio oneOf review on /api/userdata
Restructure the UserData response schemas to address the review feedback on the `oneOf` without a discriminator, and fix two accuracy bugs found while doing it. Changes - GET /api/userdata response: extract the inline `oneOf` to a named schema (`ListUserdataResponse`) and add the missing third variant returned when `split=true` and `full_info=false` (array of `[relative_path, ...path_components]`). Previously only two of the three actual server response shapes were described. - UserDataResponse (POST endpoints): correct the description — this schema is a single item, not a list — and point at the canonical `GetUserDataResponseFullFile` schema instead of the duplicate `UserDataResponseFull`. Also removes the malformed blank line in `UserDataResponseShort`. - Delete the now-unused `UserDataResponseFull` and `UserDataResponseShort` schemas (replaced by reuse of `GetUserDataResponseFullFile` and an inline string variant). - Add an `x-variant-selector` vendor extension to both `oneOf` sites documenting which query-parameter combination selects which branch, since a true OpenAPI `discriminator` is not applicable (the variants are type-disjoint and the selector lives in the request, not the response body). This keeps the shapes the server actually emits (no wire-breaking change) while making the selection rule explicit for SDK generators and readers.pull/13522/head
parent
3fcbaeefce
commit
5029490931
68
openapi.yaml
68
openapi.yaml
|
|
@ -926,15 +926,7 @@ paths:
|
||||||
content:
|
content:
|
||||||
application/json:
|
application/json:
|
||||||
schema:
|
schema:
|
||||||
oneOf:
|
$ref: "#/components/schemas/ListUserdataResponse"
|
||||||
- type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Simple filename list
|
|
||||||
- type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/GetUserDataResponseFullFile"
|
|
||||||
description: Full file info list (when full_info=true)
|
|
||||||
"404":
|
"404":
|
||||||
description: Directory not found
|
description: Directory not found
|
||||||
|
|
||||||
|
|
@ -2618,31 +2610,45 @@ components:
|
||||||
# Userdata
|
# Userdata
|
||||||
# -------------------------------------------------------------------
|
# -------------------------------------------------------------------
|
||||||
UserDataResponse:
|
UserDataResponse:
|
||||||
description: Response body for `/api/userdata` — either a list of filenames or a list of full file objects, depending on the `full_info` query parameter.
|
description: |
|
||||||
|
Response body for the POST endpoints `/api/userdata/{file}` and
|
||||||
|
`/api/userdata/{file}/move/{dest}`. Returns a single item whose
|
||||||
|
shape depends on the `full_info` query parameter.
|
||||||
|
x-variant-selector:
|
||||||
|
full_info=true: file-info object (`GetUserDataResponseFullFile`)
|
||||||
|
default: relative path string
|
||||||
oneOf:
|
oneOf:
|
||||||
- $ref: "#/components/schemas/UserDataResponseFull"
|
- $ref: "#/components/schemas/GetUserDataResponseFullFile"
|
||||||
- $ref: "#/components/schemas/UserDataResponseShort"
|
- type: string
|
||||||
|
description: Relative path of the written or moved file. Returned when `full_info` is absent or false.
|
||||||
|
|
||||||
UserDataResponseFull:
|
ListUserdataResponse:
|
||||||
type: object
|
description: |
|
||||||
description: List of files in the authenticated user's data directory, as full file objects with metadata.
|
Response body for `GET /api/userdata`. The array item shape is
|
||||||
properties:
|
determined by the `full_info` and `split` query parameters.
|
||||||
path:
|
x-variant-selector:
|
||||||
type: string
|
full_info=true: array of file-info objects (`GetUserDataResponseFullFile`)
|
||||||
size:
|
split=true: array of `[relative_path, ...path_components]` arrays
|
||||||
type: integer
|
default: array of relative path strings
|
||||||
modified:
|
oneOf:
|
||||||
type: integer
|
- type: array
|
||||||
format: int64
|
items:
|
||||||
description: Unix timestamp of last modification in milliseconds
|
$ref: "#/components/schemas/GetUserDataResponseFullFile"
|
||||||
created:
|
description: Returned when `full_info=true`.
|
||||||
type: number
|
- type: array
|
||||||
description: Unix timestamp of file creation
|
items:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
minItems: 2
|
||||||
|
description: |
|
||||||
|
Returned when `split=true` and `full_info=false`. Each inner
|
||||||
|
array is `[relative_path, ...path_components]`.
|
||||||
|
- type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: Default shape — array of file paths relative to the user data root.
|
||||||
|
|
||||||
UserDataResponseShort:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
description: List of files in the authenticated user's data directory, as filename strings only.
|
|
||||||
GetUserDataResponseFullFile:
|
GetUserDataResponseFullFile:
|
||||||
type: object
|
type: object
|
||||||
description: A single entry in a full-info user data listing.
|
description: A single entry in a full-info user data listing.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue