OpenAPI specification

[rektide]

Current Situation

It would be so excellent to have an OpenAPI specification. The current docs are not directly usable by various client generators. If we had a OpenAPI specification it would be easier to connect to SwitchBot from various systems, easier to validate correctness of our tools, we would have much better developer tools available to us.

Proposed Change

We should write an OpenAPI v3.1 or v3.0 document covering what is known/available about the switchbot api.

Additional Context

#238 is a popular, still active, but closed version of this request. I would prefer we re-open that, and close this. But we should have something open on the board. This continues to be popularly requested. We should have a way to track this popular request.

[hsakoh]

I'd like to add some perspective on what an OpenAPI spec can and cannot deliver for this API.

Where OpenAPI works: device-specific response schemas

The polymorphic responses (deviceList, status) are expressible with oneOf + discriminator on deviceType — multimeric/SwitchBotOpenAPI already demonstrates this. Two caveats though:

• The real obstacle isn't OpenAPI's expressiveness but the API's inconsistencies: deviceType strings differ between deviceList and status for some devices, IR devices use remoteType instead, and some documented field types don't match actual responses. A spec would encode these inconsistencies as machine-readable facts, which means clients generated from it would still break on real responses.
• Code generators handle a ~100-member oneOf union poorly in many target languages (fallback to untyped object, unwieldy wrapper classes). "Expressible in the spec" and "generates a usable client" are different things.

Where OpenAPI fundamentally can't help: the commands endpoint

POST /v1.1/devices/{deviceId}/commands accepts a different set of valid command/parameter combinations depending on the device type of the resource behind the path parameter. OpenAPI has no way to express "the request schema depends on an attribute of the referenced resource." The best a spec can do is one giant union of every command for every device type — which loses exactly the per-device type safety people want from codegen. On top of that, parameter is sometimes the literal string "default", sometimes a structured object, sometimes a comma-joined string like "0,255,255,255" — so even a perfect spec yields stringly-typed clients here.

Webhooks

For what it's worth, OpenAPI 3.1 does support incoming callbacks via the top-level webhooks field, so that part is covered by the spec format (tooling support is still thin).

The maintenance economics

The community-maintained spec above stalled at 2 of 3 endpoints with commands unimplemented — and I don't think that's for lack of skill. As new products keep being added to the API, keeping a hand-written spec in sync from second-hand documentation is not sustainable for a third party. A spec that drifts from reality is arguably worse than no spec, because it produces false confidence in generated code.

What would actually help

If SwitchBot wants to pursue this, the valuable version is not "someone transcribes the markdown docs into YAML" but:

1. SwitchBot generates the spec from their internal API definitions, so it's a source of truth rather than a third-hand copy.
2. The commands design gets rethought spec-first (e.g., per-device-type command schemas, or a discriminated command envelope) — the current design is the reason a spec can't deliver type-safe clients, and only the vendor can fix that.

Short of that, a partial spec would still have some value for contract testing, mock servers, and diffing between doc versions — but I'd temper expectations that it will make client development substantially easier as-is.

[hsakoh]

One constructive note, in case anyone does want to invest effort here: I'd maintain a device definition registry, not an OpenAPI document.

One small machine-readable file per device type — the deviceType strings as they actually appear (including known mismatches), status fields with observed types, valid commands with their parameter schemas, webhook shapes. From that, an OpenAPI spec, per-device typed models, and runtime validators can all be generated — the spec becomes a build artifact that can't drift on its own, and per-device generation sidesteps the giant-oneOf codegen problem.

This is the model that makes Zigbee2MQTT sustainable, with one honest caveat: SwitchBot's API community is far smaller, so this only works if the few client-library maintainers who currently each duplicate this mapping work agree to share one registry. Without that, it's just another single-maintainer artifact. So the real go/no-go question isn't "is OpenAPI feasible?" but "do 2–3 library maintainers want a common source of truth?"