OpenAPI Access

SyncTV includes built-in OpenAPI JSON and Swagger UI. The binary must be built with the openapi feature to expose these endpoints.

Enable OpenAPI

Run locally with OpenAPI:

cargo run -p synctv --features openapi --bin synctv -- serve

With an explicit config file:

cargo run -p synctv --features openapi --bin synctv -- serve --config synctv.yaml

Build check:

cargo check --workspace --all-targets --features openapi

Swagger UI

After startup:

http://localhost:8080/swagger-ui/

If server.port is changed, replace 8080.

Production example:

https://api.example.com/swagger-ui/

OpenAPI JSON

JSON document:

http://localhost:8080/api-docs/openapi.json

Export:

curl -fsSL http://localhost:8080/api-docs/openapi.json -o openapi.json

Authenticated business APIs use Bearer Token security in the OpenAPI document. Public APIs are marked accordingly.

Generate Clients

TypeScript types:

npx openapi-typescript http://localhost:8080/api-docs/openapi.json -o synctv-api.d.ts

OpenAPI Generator:

openapi-generator-cli generate \
  -i http://localhost:8080/api-docs/openapi.json \
  -g typescript-fetch \
  -o ./generated/synctv-client

Other compatible tools include orval and Kiota.

Deployment Notes

Before exposing Swagger UI in production:

Build the binary with the openapi feature.
Allow /swagger-ui/ through the reverse proxy.
Allow /api-docs/openapi.json through the reverse proxy.
Restrict access at Ingress, Nginx, gateway, or firewall level if only internal developers should access it.

To avoid exposing API structure in production, build without the openapi feature. For Docker builds, pass an explicit feature set:

docker build \
  --build-arg SYNCTV_BUILD_NO_DEFAULT_FEATURES=true \
  --build-arg SYNCTV_BUILD_FEATURES="k8s,mimalloc,tls-aws-lc,tls-webpki-roots,tls-native-roots" \
  -t synctv:production-no-openapi .