# API DSL support

Milestone 2 supports a practical go-zero-style `.api` subset.

## Supported syntax

```go
syntax = "v1"

type Request {
    Name string `path:"name"`
}

type Response {
    Message string `json:"message"`
}

@server(
    group: hello
    prefix: /api/v1
    middleware: trace,auth
    jwt: Auth
)
service hello-api {
    @handler GreetHandler
    get /hello/:name(Request) returns (Response);
}
```

Supported route methods: `get`, `post`, `put`, `delete`, `patch`.

Supported tags for OpenAPI: `path`, `query`, `header`, `json`, `body`.

## CLI

```bash
rs-zero api validate -f hello.api
rs-zero api openapi -f hello.api -o openapi.json
rs-zero api gen -f hello.api -d ./target/generated
```

Generation refuses to overwrite existing files unless `--force` is passed.

## Current limits

- No import/include support.
- No RPC generation.
- No database or cache model generation.
- No full goctl compatibility guarantee.

## Milestone 5 goctl compatibility

The API parser now resolves local `import` statements, keeps `@server` options, preserves handler docs and exposes `format_api` for stable `.api` output. OpenAPI export uses `prefix` for paths and `group` as the operation tag. Compatibility tests are based on reduced goctl fixtures in `tests/fixtures/goctl/api/`.
