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.
This commit is contained in:
Matt Miller 2026-04-22 14:02:51 -07:00
parent 3fcbaeefce
commit 5029490931

View File

@ -926,15 +926,7 @@ paths:
content:
application/json:
schema:
oneOf:
- 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)
$ref: "#/components/schemas/ListUserdataResponse"
"404":
description: Directory not found
@ -2618,31 +2610,45 @@ components:
# Userdata
# -------------------------------------------------------------------
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:
- $ref: "#/components/schemas/UserDataResponseFull"
- $ref: "#/components/schemas/UserDataResponseShort"
- $ref: "#/components/schemas/GetUserDataResponseFullFile"
- type: string
description: Relative path of the written or moved file. Returned when `full_info` is absent or false.
UserDataResponseFull:
type: object
description: List of files in the authenticated user's data directory, as full file objects with metadata.
properties:
path:
type: string
size:
type: integer
modified:
type: integer
format: int64
description: Unix timestamp of last modification in milliseconds
created:
type: number
description: Unix timestamp of file creation
ListUserdataResponse:
description: |
Response body for `GET /api/userdata`. The array item shape is
determined by the `full_info` and `split` query parameters.
x-variant-selector:
full_info=true: array of file-info objects (`GetUserDataResponseFullFile`)
split=true: array of `[relative_path, ...path_components]` arrays
default: array of relative path strings
oneOf:
- type: array
items:
$ref: "#/components/schemas/GetUserDataResponseFullFile"
description: Returned when `full_info=true`.
- type: array
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:
type: object
description: A single entry in a full-info user data listing.