管理 API 规范

本页面适用于 Apigee 和 Apigee Hybrid。

本文档介绍了如何在 API Hub 中管理 API 规范。另请参阅 API 规范简介。

向版本添加 API 规范

您可以向 API 版本添加一个或多个 API 规范。从以下选项中选择：

在创建版本时添加规范
向现有版本添加规范

在创建版本时添加规范

您可以仅使用界面，在创建版本的同时添加 API 规范。您可以提供能够访问的规范的网址，或者直接从系统上传规范文件。

控制台

如需向新版本添加规范，请执行以下操作：

按照创建 API 版本中列出的步骤开始操作。转到添加新版本页面后，您可以有选择地向版本添加规范文件：
1. 输入规范文件的显示名称。您可以根据自己所需使用任何名称。
2. 选择规范文件类型。规范类型是可配置的系统属性。另请参阅系统属性。
3. 提供指向您有权访问的有效 API 规范文件的 URI，或浏览到系统上的 API 规范文件。
4. （可选）如果您想对上传的规范文件进行严格的验证，请选中限制上传包含错误的规范文件复选框。选择此选项后，系统不会上传包含验证错误的规范。默认情况下，系统会上传包含错误的规范。
填写添加新版本页面，完成后点击创建。

向现有版本添加规范

您可以使用界面或 REST API 向现有版本添加 API 规范。

控制台

如需直接向版本添加规范，请执行以下操作：

在 Google Cloud 控制台中，转到 API Hub 页面。
转到 API Hub
点击 API。
找到具有您要修改的版本的 API。使用过滤条件指定关键字以过滤 API 列表。如果需要，请使用搜索查找 API。
选择一个 API。
点击 Add specification file（添加规范文件）。
输入规范文件的显示名称。您可以根据自己所需使用任何名称。
选择规范文件类型。规范类型是可配置的系统属性。另请参阅系统属性。
提供指向您有权访问的有效 API 规范文件的 URI，或浏览到系统上的 API 规范文件。
（可选）如果您想对上传的规范文件进行严格的验证，请选中限制上传包含错误的规范文件复选框。选择此选项后，系统不会上传包含验证错误的规范。默认情况下，系统会上传包含错误的规范。
选择要向其添加规范文件的版本。
点击创建。
注意：只有 JSON 和 YAML 格式的 OpenAPI 规范（v.2.0、v3.0 和 v3.1）支持 API 规范解析。

REST

如需向版本添加 API 规范，请使用添加 API 规范 API：

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

替换以下内容：

API_PROJECT：API Hub 宿主项目的名称。预配 API Hub 时选择了宿主项目。
API_LOCATION：宿主项目的位置。该位置是在预配 API Hub 时选择的。
API_ID：API 资源的唯一 ID。
VERSION_ID：附加到 API 资源的版本的 ID。
SPEC_ID：（可选）规范的标识符。如果未提供，将使用系统生成的 ID。名称必须是 4-63 个字符的字符串，其中有效字符为 /[a-z][0-9]-/.
DATA_FILE or URI：包含有效 API 规范的 Base64 编码文件，或是指向规范的链接。请参阅 REST 示例。

REST 示例

在此示例中，请使用 Base64 编码的 OpenAPI 规范在 API Hub 中创建新规范。上传后，API Hub 会解析规范并创建新的规范实体，其中包含描述性元数据以及若干组操作和定义实体。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

示例输出：

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

如需返回规范详细信息，请执行以下操作：

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

输出：

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

列出规范

本部分介绍了如何列出与 API 版本关联的规范。

控制台

如需使用界面列出规范，请执行以下操作：

在 Google Cloud 控制台中，转到 API Hub 页面。
转到 API Hub
点击 API。
使用过滤条件指定关键字以过滤 API 列表。如果需要，请使用搜索查找 API。
点击某个 API 以查看其详细信息。
在版本标签页下，找到您要检查的版本。
选择一个版本。
Specification file（规范文件）部分中会列出与相应版本关联的所有规范。

REST

如需列出与 API 版本关联的规范，请使用列出规范 API：

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

替换以下内容：

HUB_PROJECT：API Hub 宿主项目的名称。预配 API Hub 时选择了宿主项目。
HUB_LOCATION：宿主项目的位置。该位置是在预配 API Hub 时选择的。
API_ID：API 资源的唯一 ID。
VERSION_ID：版本的唯一 ID。

获取规范详细信息

本部分介绍如何获取与版本关联的 API 规范的详细信息。

控制台

如需使用界面查看规范的详细信息，请执行以下操作：

在 Google Cloud 控制台中，转到 API Hub 页面。
转到 API Hub
点击 API。
找到其版本包含您要检查的规范的 API。使用过滤条件指定关键字以过滤 API 列表。如果需要，请使用搜索查找 API。
点击某个 API 以查看其详细信息。
在版本标签页下，找到您要检查的版本。
选择一个版本。
在 Specification file（规范文件）部分中，选择一项规范以查看其详细信息。

REST

如需查看规范的详细信息，请使用获取规范详细信息 API：

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

替换以下内容：

HUB_PROJECT：API Hub 宿主项目的名称。预配 API Hub 时选择了宿主项目。
HUB_LOCATION：宿主项目的位置。该位置是在预配 API Hub 时选择的。
API_ID：API 资源的唯一 ID。
VERSION_ID：版本的唯一 ID。
SPEC_ID：规范的唯一 ID。

示例输出：

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

删除 API 规范

本部分介绍如何从版本中删除 API 规范。删除规范也将从版本中删除关联的操作。

控制台

如需使用界面删除 API 资源，请执行以下操作：

在 Google Cloud 控制台中，转到 API Hub 页面。
转到 API Hub
点击 API。
找到其版本包含您要删除的规范的 API。使用过滤条件指定关键字以过滤 API 列表。如果需要，请使用搜索查找 API。
点击某个 API 以查看其详细信息。
在版本标签页下，找到包含您要删除的规范的版本。
选择相应版本。
在 Specification file（规范文件）部分中，从要删除的规范所在行的操作菜单中选择删除。
点击删除。

REST

如需从 API Hub 中删除 API 资源，请使用删除 API 资源 API：

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

替换以下内容：

HUB_PROJECT：API Hub 宿主项目的名称。预配 API Hub 时选择了宿主项目。
HUB_LOCATION：宿主项目的位置。该位置是在预配 API Hub 时选择的。
API_ID：API 资源的唯一 ID。
VERSION_ID：版本的唯一 ID。
SPEC_ID：要删除的规范的唯一 ID。

修改规范元数据

您可以修改与存储在 API Hub 中的规范相关联的部分元数据。如需查看您可以修改的元数据列表，请参阅规范补丁 API。

控制台

您可以通过 Google Cloud 控制台更改现有规范。例如，您可以更改显示名称、上传新的规范文件、更改文件类型以及修改属性：

在 Google Cloud 控制台中，转到 API Hub 页面。
转到 API Hub
点击 API。
找到其版本包含您要修改的规范的 API。使用过滤条件指定关键字以过滤 API 列表。如果需要，请使用搜索查找 API。
点击某个 API 以查看其详细信息。
在版本标签页下，找到包含您要修改的规范的版本。
选择相应版本。
在“版本”页面中，找到您要修改的规范。
从要修改的规范所在行的操作菜单中选择修改。
在规范修改面板中，您可以更改以下任何规范元数据：
- 显示名称
- 规范文件类型
- 规范文档：浏览到要上传的新规范文件。
- （可选）如果您想对上传的规范文件进行严格的验证，请选中限制上传包含错误的规范文件复选框。选择此选项后，系统不会上传包含验证错误的规范。默认情况下，系统会上传包含错误的规范。
- 用户定义的属性（如果有）
点击保存。

REST

如需使用 REST API 修改规范，请执行以下操作：

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

替换以下内容：

HUB_PROJECT：API Hub 宿主项目的名称。预配 API Hub 时选择了宿主项目。
HUB_LOCATION：宿主项目的位置。该位置是在预配 API Hub 时选择的。
API_ID：API 资源的唯一 ID。
VERSION_ID：版本的唯一 ID。
SPEC_ID：规范的唯一 ID。
请求正文：使用请求正文指定要更改的属性。请参阅规范资源定义。

查看规范 lint 结果

API Hub 提供了一个内置 (Spectral) linter（验证器）以用于验证 API 的 Open API 规范。请参阅验证 API 规范。

在 Google Cloud 控制台中，转到 API Hub 页面。
转到 API Hub
点击 API。
找到其版本包含您要检查的规范的 API。使用过滤条件指定关键字以过滤 API 列表。如果需要，请使用搜索查找 API。
点击某个 API 以查看其详细信息。
在版本标签页下，找到包含您要检查的规范的版本。
点击 Lint 结果列中的查看结果以查看 lint 结果。

获取规范内容

通过此功能，您可以查看上传到 API Hub 的规范的内容。

控制台

如需使用界面查看规范的详细信息，请执行以下操作：

在 Google Cloud 控制台中，转到 API Hub 页面。
转到 API Hub
点击 API。
找到其版本包含您要删除的规范的 API。使用过滤条件指定关键字以过滤 API 列表。如果需要，请使用搜索查找 API。
点击某个 API 以查看其详细信息。
在版本标签页下，找到包含您要检查的规范的版本。
点击规范名称以查看其内容。

REST

API 会检索已上传到 API Hub 的 API 规范的原始 Base64 编码内容。使用获取规范内容 API：

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

请替换以下内容：

HUB_PROJECT：API Hub 宿主项目的名称。预配 API Hub 时选择了宿主项目。
HUB_LOCATION：宿主项目的位置。该位置是在预配 API Hub 时选择的。
API_ID：API 资源的唯一 ID。
VERSION_ID：版本的唯一 ID。
SPEC_ID：规范的唯一 ID。

示例输出：

{
  "contents": "Base64-encoded file contents"
}