Repository navigation
docs(api): describe the device object in the Swagger spec - #1155
Conversation
DeviceResponse.device and DeviceListResponse.devices were plain
"type: object", so the API docs and generated clients showed
"device: {}". Add a Device definition with the fields the API returns:
the device row after datautil.normalize, including the computed using
and claimed fields and the iOS runtime status. No field is required,
because fields= can return any subset. Nullable fields carry
x-nullable, as Swagger 2.0 has no null type.
A unit test normalizes Android and iOS devices and validates them
against the spec with additional properties rejected, so a new device
field that is not documented fails the test.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
✅ STF CI reportAll green · 6 test tiers (6 pass / 0 fail / 0 skip) · 20 Android versions (20 with a usable device in STF) Test tiers
Android device matrix
Image = a system image is published for that API and arch. Boot = emulator reached Logs, screenshots, logcat and Playwright traces are attached to the run as artifacts · full run · commit |
- Declare z-schema, js-yaml, @types/js-yaml and autodesk-forks-sway instead of relying on hoisted transitive copies. - Build the iOS fixture the way IosBridge reports a device (no Android-only fields, non-null ios.storage). - Validate the spec with sway in a unit test. - Correct the remoteConnect, remoteConnectUrl, logs_enabled, sdk and display.inches descriptions. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
Review feedback addressed in 66828aa:
|
What was wrong
In
lib/units/api/swagger/api_v1.yaml,DeviceResponse.deviceandDeviceListResponse.devices[]were plaintype: objectwith no properties. Swagger UI and generated clients showeddevice: {}for every device endpoint:/devices,/devices/{serial},/user/devices,/user/devices/{serial},/groups/{id}/devices[/{serial}],/users/{email}/devices[/{serial}]and the origin-group PUTs on/devices/groups/{id}and/devices/{serial}/groups/{id}.What changed
Devicedefinition.DeviceResponse.deviceandDeviceListResponse.devices.itemsnow$refit.lib/types/stf.d.tsDeviceDocument, written bysaveDeviceInitialState,saveDeviceIdentityandsetDevice*inlib/db/api.ts), afterdatautil.normalize. That means:name,image,marketName,releasedAt,cpu,memory,display.inchesandbrowser.apps[].developer;usingandclaimed, andiosfor iPhones;normalizedeletes (restoreOwner,automationRelease,pendingOwnerReleases,lastOwnerRelease).present,status,ready,owner,usage,using,claimedandiosfollowdoc/device-states.mdand point to it.required, at any level, becausefields=can return any subset. Also, an origin-group PUT that changes nothing returnsdevice: {}.x-nullable: true. That is the usual extension, and client generators honour it.Response validation
lib/units/api/config/default.yamlsetsvalidateResponse: true, but in practice nothing validates responses:swagger_validatorfitting validates requests only.autodesk-forks-swagger-node-runnervalidates responses only when something listens forresponseValidationError. Nothing inlib/does.So this change can't break or alter any response.
How tested
autodesk-forks-swayand ranapi.validate(), the same way the runner does. Result: 0 errors and 0 warnings, before and after.test/units/api/device-schema.mts:datautil.normalizeand validates them against the spec with z-schema, readingx-nullableas nullable. The devices are a held Android device, an absent one, one held by someone else, an iPhone withiosstatus, afields=subset and an empty{}.assumeAdditional, which rejects properties the schema doesn't list. A device field the API returns but the spec doesn't document fails the test. One case checks that rejection.npm run lint(jsonlint, eslint, typecheck, translate-check): 0 errors.npm run test:unit: 825 mocha tests and 84 ios-prototype tests pass.🤖 Generated with Claude Code