# API DSL 手册

本手册是查阅入口。完整语法说明保留在旧路径：[API DSL support](../api-dsl.md)。

## 能力概览

`rzcli api` 支持 go-zero 风格 `.api` 子集：

- `syntax = "v1"`
- `import "file.api"`
- `type` 和 field tags
- `@server` group、prefix、middleware、jwt、jwtTransition
- `service`、`@handler`、HTTP route、request/response type
- OpenAPI 导出
- 稳定格式化

## CLI

```bash
cargo run -p rs-zero-cli -- api validate -f examples/api-hello/hello.api
cargo run -p rs-zero-cli -- api format -f examples/api-hello/hello.api -o target/hello.api
cargo run -p rs-zero-cli -- api openapi -f examples/api-hello/hello.api -o target/openapi.json
cargo run -p rs-zero-cli -- api gen -f examples/api-hello/hello.api -d target/generated
```

## 相关测试

- `cargo test -p rs-zero-cli --test api_parser_integration`
- `cargo test -p rs-zero-cli --test api_openapi_integration`
- `cargo test -p rs-zero-cli --test goctl_api_compat`

## 限制

rs-zero 关注 Rust-first 输入兼容，不承诺 goctl 输出逐字一致。
