<commit_before># API注解

leap的API开发是按照`JAX-RS`标准实现的，注解的使用方法基本按照标准规定的方式使用。

## 路径注解

路径注解决定了一个Action需要使用怎么样的uri访问，一般来说，Action的uri组成如下：

```
/{base-path}/{controller_path}/{action_path}
```

这里`base-path`我们在api配置了，`controller_path`是在controller上通过`@Path`注解指定的，如果没有指定，默认是`@Path("/")`这样的注解，最后的`action_path`有两种方式指定，一种是通过`@Path`和请求方法注解（`@GET`、`@POST`等）联合指定的，另一种是直接在请求方法注解中指定path。

如下：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<apis xmlns="http://www.leapframework.org/schema/web/apis">
    <api name="demo-api" base-path="/demo-api" base-package="demo.api"></api>
</apis>
```

```java
@Path("/user")public class UserController extends ApiController {
    // 使用@GET和@Path指定action的访问uri
    @GET
    @Path("/all")
    public ApiResponse<List<UserModel>> getAllUser(){
        return ApiResponse.of(UserModel.all());
    }
    // 推荐：使用@GET("/all")的方式指定action的访问uri
    @GET("/all")
    public ApiResponse<List<UserModel>> getAllUsers(){
        return ApiResponse.of(UserModel.all());
    }
}
```

上面的配置和代码，最终生成的路由表如下：

```
METHOD PATH                   ACTION                                      DEFAULT VIEW
------ ---------------------- ------------------------------------------- ------------------------------
GET    /demo-api/user/all     UserController.getAllUser                   /demo-api/user/all
GET    /demo-api/user/all     UserController.getAllUsers                  /demo-api/user/all
```

上面的例子使用的是`@GET`指定http请求方法，实际上对于其他的请求方法注解（`@POST`，`@DELETE`，`@PATCH`等）用法也是一样的。<commit_msg>Updates api/api_annotation.md<commit_after># API注解

leap的API开发是按照`JAX-RS`标准实现的，注解的使用方法基本按照标准规定的方式使用。

## 路径注解

路径注解决定了一个Action需要使用怎么样的uri访问，一般来说，Action的uri组成如下：

```
/{base-path}/{controller_path}/{action_path}
```

这里`base-path`我们在api配置了，`controller_path`是在controller上通过`@Path`注解指定的，如果没有指定，默认是`@Path("/")`这样的注解，最后的`action_path`有两种方式指定，一种是通过`@Path`和请求方法注解（`@GET`、`@POST`等）联合指定的，另一种是直接在请求方法注解中指定path。

如下：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<apis xmlns="http://www.leapframework.org/schema/web/apis">
    <api name="demo-api" base-path="/demo-api" base-package="demo.api"></api>
</apis>
```

```java
@Path("/user")public class UserController extends ApiController {
    // 使用@GET和@Path指定action的访问uri
    @GET
    @Path("/all")
    public ApiResponse<List<UserModel>> getAllUser(){
        return ApiResponse.of(UserModel.all());
    }
    // 推荐：使用@GET("/all")的方式指定action的访问uri
    @GET("/all")
    public ApiResponse<List<UserModel>> getAllUsers(){
        return ApiResponse.of(UserModel.all());
    }
}
```

上面的配置和代码，最终生成的路由表如下：

```
METHOD PATH                   ACTION                                      DEFAULT VIEW
------ ---------------------- ------------------------------------------- ------------------------------
GET    /demo-api/user/all     UserController.getAllUser                   /demo-api/user/all
GET    /demo-api/user/all     UserController.getAllUsers                  /demo-api/user/all
```

上面的例子使用的是`@GET`指定http请求方法，实际上对于其他的请求方法注解（`@POST`，`@DELETE`，`@PATCH`等）用法也是一样的。

> **注意：**按照`JAX-RS`的固定，Action的http请求方法是必须指定的，因此每一个Action都必须有至少一个请求方法注解，没有请求方法注解的函数是不会被解析为Action的。
{'fraction_non_alphanumeric': 0.22247336131740394, 'fraction_numerical': 0.0019373587342589602, 'mean_word_length': 2.86284289276808, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 2, '>': 22, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3178879', 'n_tokens_mistral': 1375, 'n_tokens_neox': 1387, 'n_words': 111}