您可以生成客户端库软件包,以允许应用使用 Endpoints Frameworks 命令行工具访问您的 API。生成客户端库时,Endpoints Frameworks 命令行工具会自动生成一个发现文档,用于描述您的 API 的表面。
您可以在 Endpoints Frameworks 库中找到 Endpoints Frameworks 命令行工具 endpointscfg.py
。如需了解如何使用 pip
安装 Endpoints Frameworks 库,请参阅安装 Endpoints Frameworks 库。请注意,以下命令假定您已在名为 lib
的目录中安装了 Endpoints Frameworks 库。此外,相关说明假定您已创建后端 API。如需查看在示例代码上使用 Endpoints Frameworks 命令行工具的示例,请参阅 Python 版 Endpoint Frameworks 教程。
通过 API 生成客户端库软件包
您可以使用 Endpoints Frameworks 命令行工具生成以下类型的客户端软件包:
Maven:此软件包包含一个
pom.xml
文件,此文件中包含 Endpoints Frameworks 和 Google API 客户端库依赖项。readme.html
文件详细介绍了对于不同类型的客户端应用您需要向pom.xml
文件添加的内容,并介绍了如何使用 Maven 为 API 构建客户端库。Gradle:此软件包包含一个
build.gradle
文件,此文件中包含 Endpoints Frameworks 和 Google API 客户端库依赖项。readme.html
文件详细介绍了对于不同类型的客户端应用,您需要向build.gradle
文件添加的内容,并详细介绍了如何使用 Gradle 为 API 构建客户端库。默认客户端软件包:此软件包包含所有依赖库和生成的
source.jar
文件,即您在客户端调用 API 时使用的 Java 库。此软件包为您的客户端提供所有 Google API 客户端库功能,包括 OAuth。readme.html
文件列出了不同类型的客户端应用所需的.jar
文件,以及有关使用客户端库的其他详细信息。
如果您要将客户端库与 Android 应用结合使用,建议您使用 Gradle 客户端软件包。
生成客户端库
如需生成客户端库,请执行以下操作:
将目录更改为包含 API
app.yaml
文件和 API 服务类的目录。或者,使用--application
选项指定应用目录的其他某个位置。调用 Endpoints Frameworks 命令行工具,类似于如下所示:
lib/endpoints/endpointscfg.py get_client_lib java -bs gradle main.EchoApi
其中
main
是包含 API 的类,EchoApi
是您的 API 名称。等待该工具生成客户端库;成功后,该工具会显示一条类似于如下所示的消息:
API client library written to ./echo-v1.zip
将客户端库 JAR 添加到您的 Android 应用。
每次修改 API 代码时都重复执行上述步骤。
除非您使用 output
选项指定其他某个输出目录,否则客户端库软件包将写入当前目录中。
命令行语法
基本语法如下所示:
/path-to/your-app/lib/endpointscfg.py get_client_lib TARGET_LANG OPTIONS CLASS_NAME
其中:
TARGET_LANG
指定要创建的客户端软件包的类型。目前,您需要提供值java
(对于 Android 等 Java 客户端)。OPTIONS
(如果提供)是选项表中显示的一项或多项。CLASS_NAME
是 API 的完全限定类名称。
选项
您可以使用以下选项:
选项名称 | 说明 | 示例 |
---|---|---|
application |
默认情况下,工具在后端 API 的当前目录中生成客户端软件包。 如果要使用其他目录生成客户端软件包,请指定包含 app.yaml 和用于实现 API 的服务类的目录的路径。 |
--application /my_path/my_api_dir |
build-system |
用于指定应生成哪种类型的客户端软件包。可指定 gradle (生成 Android Gradle 客户端软件包)、maven (生成 Maven 客户端软件包)或 default (或省略此选项)(生成仅包含依赖项库和源代码 jar 的软件包)。 |
--build-system=gradle -bs gradle |
hostname |
指定发现文档 rootURL 。此选项会替换从后端 API 项目 app.yaml ([YOUR_APP_ID].appspot.com ) 中的 application 条目和 API 修饰器中定义的 hostname 派生的默认值。此选项的一个用途是提供主机名 localhost 作为用于本地测试的 rootURL。 |
--hostname localhost |
format |
请不要指定此选项,因为支持的唯一值是默认值,即 rest (对于 REST)。 |
无需设置此项,请使用默认值。 |
output |
设置将输出写入到的目录。 默认值:从其中调用工具的目录。 |
--output /mydir -o /mydir |
受支持的客户端平台
Endpoints Frameworks 命令行工具生成的客户端软件包支持以下平台:
- Java 7 及更高版本:
- Android 1.6 及更高版本。
- App Engine。
通过 API 生成 OpenAPI 文档
endpointscfg.py
工具提供了一个用于通过 API 后端生成 OpenAPI 文档的命令。命令语法如下所示:
lib/endpoints/endpointscfg.py get_openapi_spec
[-h]
[-a APPLICATION]
[--hostname HOSTNAME]
[-o OUTPUT]
service [service ...]
positional arguments:
service Fully qualified service class name.
optional arguments:
-h, --help Show this help message and exit.
-a APPLICATION, --application APPLICATION
The path to the Python App Engine application.
--hostname HOSTNAME Default application hostname, if none is specified for the API service.
-o OUTPUT, --output OUTPUT
The directory to store output files.
--x-google-api-name Add the 'x-google-api-name' field to the generated OpenAPI document.
例如,使用 echo
示例:
$ lib/endpoints/endpointscfg.py get_openapi_spec --hostname=echo-example.appspot.com main.EchoApi
OpenAPI spec written to ./echov1openapi.json