# 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`。
