多类 API

如果某一个 API 特别复杂，您可以通过多个 Java 类来实现它。如需让不同的类属于同一个 API，您必须执行以下操作：

例如，以下两个类都属于 tictactoe API：

@Api(name = "tictactoe", version = "v1")
class TicTacToeA { … }

@Api(name = "tictactoe", version = "v1")
class TicTacToeB { … }

API 配置通过 @Api 注释属性指定。但是，对于同一 API 中的多个类，@Api 要求不仅仅是在每个类的 @Api 注释中指定相同的 name 和 version 字符串。实际上，如果类的 @Api 属性中指定的 API 配置存在任何差异，后端 API 将无法运行。多类 API 中类的 @Api 属性存在任何差异都会导致 API 配置“有歧义”，这样的配置在 App Engine 的 Cloud Endpoints Frameworks 中无法运行。

有几种方法可以创建无歧义的多类 API：

  • 手动确保单个 API 中的所有类具有完全相同的 @Api 注释属性。
  • 通过 Java 继承使用注释继承。 在此继承情况下，单个 API 中的所有类都从由 @Api 注释的公共基类继承相同的 API 配置。
  • 通过 @ApiReference 注释在单个 API 中的所有类上使用注释继承，使它们引用由 @Api 注释的公共类的同一 API 配置。

为类之间可以不同的属性使用 @ApiClass

如需使用此功能，您需要执行以下导入：

import com.google.api.server.spi.config.ApiClass;

虽然一个 API 中所有类的 @Api 注释中的属性必须匹配，但您能够使用 @ApiClass 注释来提供类之间可以不同的属性。例如：

// API methods implemented in this class allow only "clientIdA".
@Api(name = "tictactoe", version = "v1")
@ApiClass(clientIds = { "clientIdA" })
class TicTacToeA { … }

// API methods implemented in this class provide unauthenticated access.
@Api(name = "tictactoe", version = "v1")
class TicTacToeB { … }

其中 TicTacToeA 使用包含允许的客户端 ID 的白名单来限制访问权限，TicTacToeB 不限制访问权限。

由 @ApiClass 注释提供的所有属性必须在 @Api 注释中包含等效属性。请注意，@Api 等效属性充当 API 范围的默认值。如果在 @Api 中指定的同一属性存在 API 范围的默认值，则特定于类的 @ApiClass 属性将替换 API 范围的默认值。

以下示例演示了特定于类的 @ApiClass 等效属性替换 @Api 属性：

// For this class "boards" overrides "games".
@Api(name = "tictactoe", version = "v1", resource = "games")
@ApiClass(resource = "boards")
class TicTacToeBoards { … }

// For this class "scores" overrides "games".
@Api(