OpenAPI 文档入口

SyncTV 内置 OpenAPI JSON 和 Swagger UI。二进制必须启用 openapi feature 才会暴露这些入口。

启用 OpenAPI

本地启动带 OpenAPI 的服务：

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

如果还要指定配置文件：

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

编译检查：

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

Swagger UI 地址

服务启动后访问：

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

server.port 不是 8080 时，替换为实际端口。

生产或远程环境示例：

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

OpenAPI JSON 地址

OpenAPI JSON 地址：

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

导出到文件：

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

带认证访问普通业务接口时，OpenAPI 文档中的安全方案使用 Bearer Token。公共接口会在文档中标注不需要认证。

生成客户端

拿到 JSON 后，可以用 OpenAPI Generator、orval、openapi-typescript、Kiota 等工具生成客户端。

TypeScript 类型示例：

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

部署环境注意事项

生产环境暴露 Swagger UI 前确认：

二进制构建时启用了 openapi feature。
反向代理允许访问 /swagger-ui/。
反向代理允许访问 /api-docs/openapi.json。
只允许内网开发者访问时，在 Ingress、Nginx、网关或防火墙层限制来源。

不暴露 API 结构时，使用不带 openapi feature 的生产构建。Docker 构建可传入显式 feature 组合：

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 .