Skip to content

docs(api): describe the device object in the Swagger spec - #1155

Merged
koral-- merged 2 commits into
masterfrom
docs/swagger-device-schema
Nov 21, 2026
Merged

koral-- merged 2 commits into
masterfrom
docs/swagger-device-schema

Conversation

@koral--

@koral-- koral-- commented Nov 21, 2026

Copy link
Copy Markdown
Member

What was wrong

In lib/units/api/swagger/api_v1.yaml, DeviceResponse.device and DeviceListResponse.devices[] were plain type: object with no properties. Swagger UI and generated clients showed device: {} 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

  • A new Device definition. DeviceResponse.device and DeviceListResponse.devices.items now $ref it.
  • It documents what the API actually returns: the device row (lib/types/stf.d.ts DeviceDocument, written by saveDeviceInitialState, saveDeviceIdentity and setDevice* in lib/db/api.ts), after datautil.normalize. That means:
    • it includes the derived name, image, marketName, releasedAt, cpu, memory, display.inches and browser.apps[].developer;
    • it includes the computed using and claimed, and ios for iPhones;
    • it leaves out the fields normalize deletes (restoreOwner, automationRelease, pendingOwnerReleases, lastOwnerRelease).
  • The descriptions of present, status, ready, owner, usage, using, claimed and ios follow doc/device-states.md and point to it.
  • No property is required, at any level, because fields= can return any subset. Also, an origin-group PUT that changes nothing returns device: {}.
  • Swagger 2.0 has no null type, so nullable fields have x-nullable: true. That is the usual extension, and client generators honour it.

Response validation

lib/units/api/config/default.yaml sets validateResponse: true, but in practice nothing validates responses:

  • The swagger_validator fitting validates requests only.
  • autodesk-forks-swagger-node-runner validates responses only when something listens for responseValidationError. Nothing in lib/ does.

So this change can't break or alter any response.

How tested

  • The runner refuses to start on any sway error or warning, including an unused definition. I loaded the spec with the bundled autodesk-forks-sway and ran api.validate(), the same way the runner does. Result: 0 errors and 0 warnings, before and after.
  • New test/units/api/device-schema.mts:
    • It normalizes realistic devices with datautil.normalize and validates them against the spec with z-schema, reading x-nullable as nullable. The devices are a held Android device, an absent one, one held by someone else, an iPhone with ios status, a fields= subset and an empty {}.
    • It runs z-schema with 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.
    • Against the old spec, the test fails.
  • 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

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>
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

✅ STF CI report

All green  ·  6 test tiers (6 pass / 0 fail / 0 skip)  ·  20 Android versions (20 with a usable device in STF)

Test tiers

Tier Result
✅ Build (npm + webpack) deps cache miss
✅ Lint (eslint + jsonlint + translations + workflow shell) lib/, res/ and root JS + JSON, translation catalogs, and every workflow run: block
✅ Unit tests (mocha) lib/util, lib/wire and lib/db specs
✅ Component tests (vitest + React) 257 specs, 0 failed, 0 errored
✅ Integration + device-less E2E (stf local + RethinkDB + Playwright + SeaweedFS) stf local success, fake devices success, web UI suite success, storage success
✅ Docker Compose + AVD + Playwright (Android 16, API 36) 21 Playwright tests, image success, Compose/AVD success, teardown success

Android device matrix

Android API Image Boot In STF Usable SIM IDs Screen Touch Shell UI E2E Teardown
✅ 5.0 21 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 5.1 22 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 6.0 23 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 7 24 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 7.1 25 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 8 26 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 8.1 27 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 9 28 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 10 29 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 11 30 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 12 31 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 12L 32 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 13 33 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 14 34 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 15 35 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 16 36 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 16.1 36.1 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 17 37.0 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 17 37.1 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ 17 37.2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

Image = a system image is published for that API and arch. Boot = emulator reached sys.boot_completed and answers adb. In STF = the device registered with the STF provider. Usable = STF offered it as Use and handed over control. SIM IDs = imei, imsi, iccid and phoneNumber landed on the device document, which from API 23 up needs an STFService build whose agent answers --telephony (a leg whose emulator reports no usable SIM records a pass, because there is nothing to read). Screen = minicap frames reached the browser canvas and kept changing. Touch = a browser tap and swipe showed up in getevent on the device, at the coordinates they were aimed at: the tap within 5% of the centre of the touch axes, the swipe descending monotonically from 0.75 to 0.25 (the emulator runs with adb root, which minitouch needs to open /dev/input). Shell = the dashboard shell widget ran a command on it. UI E2E = the rest of the Playwright web UI suite. Teardown = the emulator action shut the AVD down and exited on its own.

Logs, screenshots, logcat and Playwright traces are attached to the run as artifacts · full run · commit 9a2ddd6

- 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>
@koral--

koral-- commented Nov 21, 2026

Copy link
Copy Markdown
Member Author

Review feedback addressed in 66828aa:

  • Declared z-schema, js-yaml (^4, the test had been using the hoisted 3.15.2), @types/js-yaml and autodesk-forks-sway as devDependencies; dropped the createRequire cast for js-yaml.
  • The iOS fixture no longer spreads the Android one: it matches what IosBridge reports (no product/CPU/memory/GL/display.size, no Android-only blocks) and has a non-null ios.storage.
  • Added a test that runs sway's api.validate() and expects 0 errors and 0 warnings.
  • Fixed the descriptions of display.inches (physical xdpi/ydpi), remoteConnect/remoteConnectUrl (admins see them too), logs_enabled (legacy, always false) and sdk (iOS: same as version).

@koral--
koral-- merged commit 9d3a7a8 into master Nov 21, 2026
45 of 46 checks passed
@koral--
koral-- deleted the docs/swagger-device-schema branch November 21, 2026 01:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant