编写代码并为其添加注释

本页面介绍了如何设计 Cloud Endpoints Frameworks 代码的结构并为其添加注释。如需查看所有受支持的注释的完整列表，请参阅注释。

准备工作

  1. 设置您的开发环境。

  2. 克隆 Endpoints Frameworks 框架示例：

     git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

  3. Endpoints Framework 框架示例位于：

     cd appengine-java8/endpoints-v2-skeleton/

为帮助说明注释的工作原理，本文档使用 endpoints-v2-backend 示例来显示注释和其他代码，您必须将注释和代码添加到 endpoints-v2-skeleton 示例才能完成构建。最后，修改后的 endpoints-v2-skeleton 示例的行为与 endpoints-v2-backend 示例相同，后者用于 App Engine 上的 Endpoints Frameworks 使用入门。

创建代码和为代码添加注释

要为代码添加注释，请执行以下操作：

  1. 将目录更改为项目的 Java 源目录，例如：src/main/java/com/example/skeleton。
  2. 创建一个名为 Message.java 并包含以下代码的 JavaBean 类文件： 
    public class Message {

  private String message;

  public String getMessage() {
    return this.message;
  }

  public void setMessage(String message) {
    this.message = message;
  }
}
  3. 修改框架示例中包含的 MyApi.java 文件。将 @Api 定义注解更改为以下内容： 
    @Api(
    name = "echo",
    version = "v1",
    namespace =
    @ApiNamespace(
        ownerDomain = "echo.example.com",
        ownerName = "echo.example.com",
        packagePath = ""
    ),
    // ...
)

    version = "v1" 属性指定了示例 API 的版本。您输入的值将成为 API 网址中路径的一部分。如需详细了解版本，请参阅处理 API 版本控制。

  4. 将以下 echo 方法添加为您的第一个 API 端点，并将 doEcho 帮助程序方法添加到您的 MyApi.java。 
    @ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}
     
    private Message doEcho(Message request, Integer n) {
  Message response = new Message();
  if (n != null && n >= 0) {
    StringBuilder sb = new StringBuilder();
    for (int i = 0; i < n; i++) {
      if (i > 0) {
        sb.append(' ');
      }
      sb.append(request.getMessage());
    }
    response.setMessage(sb.toString());
  }
  return response;
}
  5. 从 Echo.java 复制所有导入项并将其粘贴到 MyApi.java 中。

  6. Maven

    构建项目：

    mvn clean package

    Gradle

    构建项目：

    gradle clean build

注释基础知识

后端 API 中有三种常用的注释：

  • @Api，包含后端 API 的配置详细信息。
  • @ApiMethod，标记属于后端 API 的类方法。当您生成客户端库和发现文档时，未使用 @ApiMethod 进行标记的方法不包括在内。@ApiMethod 注释也可用于替换特定方法的 API 配置。
  • @Named，除非参数是实体类型，否则必须将此注释添加到传递给服务器端方法的所有参数。

如需查看所有 Endpoints Frameworks 注释的完整列表，请参阅注释和语法。

后续步骤