# API codegen 教程
## 目标
使用 go-zero 风格 `.api` 文件完成校验、格式化、OpenAPI 导出和 Rust REST skeleton 生成。
## 输入文件
示例文件：`examples/api-hello/hello.api`。
支持的核心语法见 [API DSL 手册](../manual/api-dsl.md)。goctl 兼容边界见 [goctl 兼容矩阵](../goctl-compatibility.md)。
## 校验 `.api`
```bash
cargo run -p rs-zero-cli -- api validate -f examples/api-hello/hello.api
```
校验会检查 service、handler、HTTP method、request/response type 引用等语义。
## 格式化 `.api`
```bash
cargo run -p rs-zero-cli -- api format \
-f examples/api-hello/hello.api \
-o target/hello.formatted.api
```
格式化会保留 import、docs、server options、handler 和 field tags。输出文件已存在时默认拒绝覆盖，需要覆盖时添加 `--force`。
## 导出 OpenAPI
```bash
cargo run -p rs-zero-cli -- api openapi \
-f examples/api-hello/hello.api \
-o target/openapi.json
```
OpenAPI 导出会使用 route path、path/query/header/form tags、response schema、`@server` prefix 和 group metadata。
## 生成 REST skeleton
```bash
cargo run -p rs-zero-cli -- api gen \
-f examples/api-hello/hello.api \
-d target/generated
```
生成结果是 Rust-first REST skeleton，不承诺与 goctl 生成的 Go 文件逐字一致。
## 验证
```bash
cargo test -p rs-zero-cli --test goctl_api_compat
cargo test -p rs-zero-cli api
```
## 常见问题
- `unknown request type`：route 引用了未定义的 type，检查 `.api` 中 type 名称。
- `missing import`：相对 import 文件不存在，检查路径是否相对当前 `.api` 文件。
- `target file already exists`：CLI 默认不覆盖文件；确认无误后使用 `--force`。