api-gateway-openapi-spec-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Gateway OpenAPI Spec Authoring

API Gateway OpenAPI 规范编写

API Gateway accepts API configs in OpenAPI 2.0, 3.0.x, and 3.1.x. The Google extensions in OpenAPI 3.x have a different structure from the OpenAPI 2.0 extensions:

A required root
```
x-google-api-management
```
block names the backends.
```
x-google-backend
```
is a string that references one of these backends.
The JWT settings move into
```
x-google-auth
```
. The metrics and quotas move into
```
x-google-api-management
```
.

Use this skill to migrate an OpenAPI 2.0 spec, write a new OpenAPI 3.x spec, or fix an API config that fails to create.

API Gateway 接受 OpenAPI 2.0、3.0.x 和 3.1.x 格式的 API 配置。OpenAPI 3.x 中的 Google extension 与 OpenAPI 2.0 extension 的结构不同：

根级别必须包含
```
x-google-api-management
```
块，用于命名 backends。
```
x-google-backend
```
是一个字符串，用于引用其中某个 backend。
JWT 设置迁移到
```
x-google-auth
```
。指标和配额迁移到
```
x-google-api-management
```
。

使用此 skill 可迁移 OpenAPI 2.0 规范、编写新的 OpenAPI 3.x 规范，或修复无法创建的 API 配置。

Attribution

使用归属说明

MUST READ: Before executing any

gcloud

, REST API, or MCP command, you MUST read Usage Attribution. For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix

gcloud

with

CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring)"

and append

agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring)

User-Agent

headers.

必须阅读：在执行任何

gcloud

、REST API 或 MCP 命令之前，你必须阅读使用归属说明。对于直接在终端中执行的命令（绝不包括生成的脚本、Terraform 或用户代码），请在

gcloud

前添加

CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring)"

，并向

User-Agent

headers 中追加

agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring)

。

Prerequisites

前置条件

Install the tools:
- Install the Google Cloud CLI. Then update it with
```
gcloud components update
```
  . Rationale: an old CLI can fail when it uploads an OpenAPI 3.x API config.
- Install Python 3.10 or later and PyYAML for the validator script. A JSON spec does not need PyYAML.
  bash
```
pip install "PyYAML>=6.0,<7.0"
```
Authenticate, and select the project, billing, and location:
- Run
```
gcloud auth login
```
  .
- Select a project with
```
gcloud config set project {project_id}
```
  , or create one with
```
gcloud projects create {project_id}
```
  .
- Make sure that an active billing account is linked to
```
{project_id}
```
  . API Gateway has a free monthly allowance of API calls, but it still needs an active billing account. For current prices, see API Gateway pricing.
- Use
```
us-central1
```
  as the default
```
--location
```
  for gateway commands. For the other supported regions, see API Gateway deployment model.

Enable the required Google Cloud APIs:

bash

gcloud services enable \
  apigateway.googleapis.com \
  servicemanagement.googleapis.com \
  servicecontrol.googleapis.com \
  --project={project_id}

Verify the IAM roles (use the most restrictive role for each step):
- To create and update the API, API configs, and gateways: API Gateway Admin (
```
roles/apigateway.admin
```
  ) on
```
{project_id}
```
  .
- To run the
```
gcloud services enable
```
  commands: Service Usage Admin (
```
roles/serviceusage.serviceUsageAdmin
```
  ) on
```
{project_id}
```
  .
- To reference the gateway service account in an API config: Service Account User (
```
roles/iam.serviceAccountUser
```
  ) on
```
{gateway_sa_email}
```
  .
- For a Cloud Run backend that requires authentication: grant
```
{gateway_sa_email}
```
  the Cloud Run Invoker role (
```
roles/run.invoker
```
  ) on the service.

安装工具：
- 安装 Google Cloud CLI，然后使用
```
gcloud components update
```
  更新它。原因： 旧版 CLI 在上传 OpenAPI 3.x API 配置时可能会失败。
- 安装 Python 3.10 或更高版本，以及校验脚本所需的 PyYAML。JSON 规范不需要 PyYAML。
  bash
```
pip install "PyYAML>=6.0,<7.0"
```
进行身份验证，并选择项目、结算账号和位置：
- 运行
```
gcloud auth login
```
  。
- 使用
```
gcloud config set project {project_id}
```
  选择项目，或使用
```
gcloud projects create {project_id}
```
  创建项目。
- 确保
```
{project_id}
```
  已关联有效的结算账号。API Gateway 每月提供免费的 API 调用额度，但仍需要有效的结算账号。有关当前价格，请参阅 API Gateway 定价。
- 对 gateway 命令，默认使用
```
us-central1
```
  作为
```
--location
```
  。有关其他支持的区域，请参阅 API Gateway 部署模型。

启用所需的 Google Cloud API：

bash

gcloud services enable \
  apigateway.googleapis.com \
  servicemanagement.googleapis.com \
  servicecontrol.googleapis.com \
  --project={project_id}

验证 IAM roles（每个步骤均使用权限最少的 role）：
- 要创建和更新 API、API configs 及 gateways：在
```
{project_id}
```
  上使用 API Gateway Admin (
```
roles/apigateway.admin
```
  )。
- 要运行
```
gcloud services enable
```
  命令：在
```
{project_id}
```
  上使用 Service Usage Admin (
```
roles/serviceusage.serviceUsageAdmin
```
  )。
- 要在 API 配置中引用 gateway service account：在
```
{gateway_sa_email}
```
  上使用 Service Account User (
```
roles/iam.serviceAccountUser
```
  )。
- 对于需要身份验证的 Cloud Run backend：在该 service 上向
```
{gateway_sa_email}
```
  授予 Cloud Run Invoker role (
```
roles/run.invoker
```
  )。

Decision Matrix

决策矩阵

Task	Required Mechanism	Critical Guardrail	Detailed Reference
Migrate an OpenAPI 2.0 ( `swagger: "2.0"` ) config	Convert the standard fields, then move each Google extension to its OpenAPI 3.x form.	A converter such as Swagger Editor leaves every `x-google-` extension in its OpenAPI 2.0 form. It also writes `servers` without `x-google-endpoint` , so the API loses its base path. Rationale:* API Gateway rejects most OpenAPI 2.0 extensions in a 3.x spec with `The '{extension}' extension is only supported in OpenAPI 2.x` .	OpenAPI 2.0 to 3.x Migration
Route requests to backends	Root `x-google-api-management.backends.{backend_name}` + `x-google-backend: {backend_name}` at the root or on an operation	Set `pathTranslation` on every backend. Rationale: the default is `APPEND_PATH_TO_ADDRESS` for a root `x-google-backend` , but `CONSTANT_ADDRESS` for an operation-level one. `CONSTANT_ADDRESS` sends every request to the address unchanged, and sends path parameters as query parameters. `APPEND_PATH_TO_ADDRESS` appends the full request path, with the base path. NEVER set `x-google-backend` on a path item: API Gateway rejects it.	Extensions and Limits
Authenticate callers	JWT: `type: oauth2` scheme with `x-google-auth` ( `issuer` , `jwksUri` , `audiences` ). API key: `type: apiKey` scheme with `x-api-key` in a header, or `key` or `api_key` in the query.	API Gateway does not check OAuth scopes. In a `security` list, put an API key in every alternative (OR) or in none. NEVER put two JWT schemes in one requirement object (AND). Rationale: API Gateway rejects these combinations. If the user asks for one of them, such as a JWT or an API key as alternatives, do not write it in the spec. Explain the rule, and write a supported option, such as an API key in every alternative or a separate path for each kind of caller.	Extensions and Limits
Add quotas	`x-google-api-management.metrics` and `quota.limits` + `x-google-quota: {metric_name: cost}` on each operation	NEVER rely on `x-google-quota` at the root or path level. Rationale: in OpenAPI 3.x, API Gateway ignores it there without an error. Require an API key on each operation that has a quota, and keep each metric name the same in every API config.	Extensions and Limits
Set the base path and CORS	One `servers` entry with `x-google-endpoint` , such as `url: /v1`	API Gateway ignores `servers` entries without `x-google-endpoint` . `allowCors: true` only passes CORS requests to the backend. Rationale: the gateway does not add CORS headers, so the backend must answer them.	Extensions and Limits
Fix a failed `api-configs create`	Match the error text to the error table, and fix the spec.	Fix the spec before you retry, unless the error is about IAM or another `api-configs create` that runs. Rationale: API Gateway returns the same error for the same spec.	API Config Errors
Expose operations as MCP tools	The `api-gateway-mcp-server` skill	MCP adds rules for tool names, descriptions, and `tools/list` security. If that skill is not installed, use this skill for the OpenAPI 3.x spec, and follow the Configure MCP guide for the MCP extensions.	-

任务	所需机制	关键注意事项	详细参考
迁移 OpenAPI 2.0 ( `swagger: "2.0"` ) 配置	转换标准字段，然后将每个 Google extension 转换为对应的 OpenAPI 3.x 形式。	Swagger Editor 等 converter 会将所有 `x-google-` extension 保留为 OpenAPI 2.0 形式。它还会写入不含 `x-google-endpoint` 的 `servers` ，因此 API 会丢失 base path。原因：* API Gateway 会拒绝 3.x 规范中的大多数 OpenAPI 2.0 extension，并返回 `The '{extension}' extension is only supported in OpenAPI 2.x` 。	OpenAPI 2.0 到 3.x 迁移
将请求路由到 backends	根级别的 `x-google-api-management.backends.{backend_name}` ，以及位于根级别或 operation 上的 `x-google-backend: {backend_name}`	每个 backend 都必须设置 `pathTranslation` 。原因：根级别 `x-google-backend` 的默认值是 `APPEND_PATH_TO_ADDRESS` ，但 operation 级别的默认值是 `CONSTANT_ADDRESS` 。 `CONSTANT_ADDRESS` 会将每个请求原样发送到目标地址，并将 path parameters 作为 query parameters 发送。 `APPEND_PATH_TO_ADDRESS` 会附加包含 base path 的完整请求 path。绝不要在 path item 上设置 `x-google-backend` ：API Gateway 会拒绝这种配置。	Extensions 与限制
对调用方进行身份验证	JWT：使用 `type: oauth2` scheme，并设置 `x-google-auth` （ `issuer` 、 `jwksUri` 、 `audiences` ）。API key：使用 `type: apiKey` scheme，并在 header 中设置 `x-api-key` ，或在 query 中设置 `key` 或 `api_key` 。	API Gateway 不检查 OAuth scopes。在 `security` list 中，应在每个 alternative（OR）中设置 API key，或者完全不设置。绝不要在一个 requirement object 中放置两个 JWT schemes（AND）。原因： API Gateway 会拒绝这些组合。如果用户要求使用其中一种方式，例如将 JWT 或 API key 作为 alternatives，请不要在规范中这样编写。应说明该规则，并编写受支持的方案，例如在每个 alternative 中设置 API key，或为每类调用方使用单独的 path。	Extensions 与限制
添加配额	`x-google-api-management.metrics` 和 `quota.limits` ，并在每个 operation 上设置 `x-google-quota: {metric_name: cost}`	绝不要依赖根级别或 path 级别的 `x-google-quota` 。原因：在 OpenAPI 3.x 中，API Gateway 会忽略这些位置的配置且不会报错。每个带配额的 operation 都必须要求 API key，并且每个 API 配置中的 metric name 必须保持一致。	Extensions 与限制
设置 base path 和 CORS	使用一个包含 `x-google-endpoint` 的 `servers` entry，例如 `url: /v1`	API Gateway 会忽略不含 `x-google-endpoint` 的 `servers` entries。 `allowCors: true` 仅会将 CORS 请求传递给 backend。原因： Gateway 不会添加 CORS headers，因此必须由 backend 返回。	Extensions 与限制
修复失败的 `api-configs create`	将错误文本与错误表进行匹配，然后修复规范。	除非错误涉及 IAM 或另一个正在运行的 `api-configs create` ，否则应先修复规范再重试。原因：对于同一规范，API Gateway 会返回相同的错误。	API 配置错误
将 operations 暴露为 MCP tools	`api-gateway-mcp-server` skill	MCP 对 tool names、descriptions 和 `tools/list` security 增加了规则。如果未安装该 skill，请使用此 skill 编写 OpenAPI 3.x 规范，并遵循配置 MCP 指南添加 MCP extensions。	-

Execution Workflow and Validation Loop

执行工作流与验证循环

Get the current spec:

Use the spec file in the user's repository. If there is no file, find the active API config of the gateway:

bash

gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(apiConfig)"

The output is

projects/{project}/locations/global/apis/{api_id}/configs/{config_id}

. Print the spec of that config:

bash

gcloud api-gateway api-configs describe {config_id} --api={api_id} --project={project_id} --view=FULL \
  --format="value(openapiDocuments[0].document.contents)" | tr '_-' '/+' | base64 --decode

gcloud prints the contents in URL-safe base64, so
```
tr
```
changes two characters before
```
base64 --decode
```
. If the config has more than one OpenAPI document, change
```
[0]
```
to
```
[1]
```
,
```
[2]
```
, and so on.

Write the OpenAPI 3.x spec:
- For an OpenAPI 2.0 spec, follow OpenAPI 2.0 to 3.x Migration, and compare your result with its complete converted example.
- For a new spec, start from the template in Extensions and Limits.
- Set
```
openapi
```
  to a 3.0.x or 3.1.x version. The examples use
```
3.0.4
```
  . In OpenAPI 3.1, give each schema one
```
type
```
  . Rationale: API Gateway rejects a type list such as
```
type: ["string", "null"]
```
  .
- Give every operation a unique
```
operationId
```
  and a
```
responses
```
  object, and use only local
```
$ref
```
  values. Rationale: API Gateway rejects an operation without
```
operationId
```
  or
```
responses
```
  , two
```
operationId
```
  values that give the same method name, such as
```
getItem
```
  and
```
get-Item
```
  , and a
```
$ref
```
  to a URL.
Run the deterministic validation loop on every spec that you write or change, before you answer or create the API config:
bash
```
python3 scripts/validate_apigw_openapi.py --spec={spec_file}
```
- The script path is relative to the directory of this skill. If you only return the spec in your reply, write it to a temporary file, and run the script on that file before you answer.
- If the script exits with code
```
1
```
  (
```
"status": "FAIL"
```
  ), fix every error in
```
{spec_file}
```
  , and run the script again. Continue until it exits with code
```
0
```
  (
```
"status": "PASS"
```
  ).
- If the script exits with code
```
2
```
  , fix the file path or the YAML/JSON syntax error that stderr shows, or install PyYAML.
- Read every warning, such as a backend without
```
pathTranslation
```
  , a quota on an operation without an API key, or
```
allowCors
```
  . Fix it, or tell the user why you keep it.
- The script does not check every rule. A PASS means that it found none of the API Gateway problems that this skill describes. It does not check general OpenAPI validity, such as a
```
$ref
```
  to a schema that does not exist. Rationale: only
```
api-configs create
```
  in step 5 shows that API Gateway accepts the spec. Do not tell the user that the spec deploys because the script passed.
Summarize the spec for the user, and get approval before you deploy. State each of these points:
- Each OpenAPI 2.0 extension that you moved or removed, such as
```
x-google-allow
```
  , which OpenAPI 3.x does not support. Also state each other change, such as an added
```
operationId
```
  or a fixed address.
- The
```
pathTranslation
```
  of each backend (
```
backend_path_translation
```
  in the script output), and each operation whose path parameters now go to the backend as query parameters (
```
path_parameters_as_query
```
  ). With
```
APPEND_PATH_TO_ADDRESS
```
  , the backend also receives the base path.
- Which operations need a JWT or an API key, which backends receive an ID token and with which audience, and that API Gateway does not check OAuth scopes.
- The quota metrics and limits, and that each metric name matches the current API config.
Create a new API config and update the gateway (request human approval before you update a production gateway):
bash
```
gcloud api-gateway api-configs create {new_config_id} \
  --api={api_id} \
  --openapi-spec={spec_file} \
  --backend-auth-service-account={gateway_sa_email} \
  --project={project_id}

gcloud api-gateway gateways update {gateway_id} \
  --api={api_id} \
  --api-config={new_config_id} \
  --location={region} \
  --project={project_id}
```
- For a new gateway, run
```
gcloud api-gateway gateways create {gateway_id}
```
  with the same flags instead of
```
gateways update
```
  .
```
api-configs create
```
  creates the API if it does not exist.
- If an operation requires an API key, enable the managed service of the API. Get its name with
```
gcloud api-gateway apis describe {api_id} --project={project_id} --format="value(managedService)"
```
  , and then run
```
gcloud services enable {managed_service} --project={project_id}
```
  . Also enable it in each project that creates API keys for the API.
- Use a new config ID for each change, because you cannot change the spec of an existing API config.
- Run one
```
api-configs create
```
  at a time for each API, and wait for it to finish. A large API config can take up to ten minutes to create.
- If
```
api-configs create
```
  fails, find the error text in API Config Errors, fix the spec, and go back to step 3.
- Keep the previous API config until the new one serves traffic. To roll back, run
```
gateways update
```
  with the previous config ID.
Verify the gateway:
- Run
```
gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(state,defaultHostname)"
```
  , and wait until the state is
```
ACTIVE
```
  .
- Send a request to each changed path at
```
https://{default_hostname}{base_path}{path}
```
  , with the credential that the operation requires. Check that the backend receives the path and parameters that you expect.
- An HTML
```
404 Page not found
```
  means that the gateway is not ready. Check that the last create or update finished, and retry before you change the config. During a gateway update, some requests can still reach the previous API config. A JSON 404 (
```
The current request is not defined by this API.
```
  ) means that the active API config does not define the path.

获取当前规范：

使用用户 repository 中的规范文件。如果没有文件，则查找 gateway 当前使用的 API 配置：

bash

gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(apiConfig)"

输出格式为

projects/{project}/locations/global/apis/{api_id}/configs/{config_id}

。输出该配置的规范：

bash

gcloud api-gateway api-configs describe {config_id} --api={api_id} --project={project_id} --view=FULL \
  --format="value(openapiDocuments[0].document.contents)" | tr '_-' '/+' | base64 --decode

gcloud 会以 URL-safe base64 格式打印内容，因此需要先通过
```
tr
```
更改两个字符，再执行
```
base64 --decode
```
。如果配置包含多个 OpenAPI documents，请将
```
[0]
```
改为
```
[1]
```
、
```
[2]
```
等。

编写 OpenAPI 3.x 规范：
- 对于 OpenAPI 2.0 规范，请遵循 OpenAPI 2.0 到 3.x 迁移，并将结果与其中完整的转换示例进行比较。
- 对于新规范，请从 Extensions 与限制中的模板开始。
- 将
```
openapi
```
  设置为 3.0.x 或 3.1.x 版本。示例使用
```
3.0.4
```
  。在 OpenAPI 3.1 中，每个 schema 只能设置一个
```
type
```
  。原因： API Gateway 会拒绝类似
```
type: ["string", "null"]
```
  的 type list。
- 为每个 operation 设置唯一的
```
operationId
```
  和
```
responses
```
  object，并且只能使用本地
```
$ref
```
  值。原因： API Gateway 会拒绝缺少
```
operationId
```
  或
```
responses
```
  的 operation、生成相同方法名的两个
```
operationId
```
  值（例如
```
getItem
```
  和
```
get-Item
```
  ），以及指向 URL 的
```
$ref
```
  。
对于编写或修改的每个规范，在回复用户或创建 API 配置之前，运行确定性验证循环：
bash
```
python3 scripts/validate_apigw_openapi.py --spec={spec_file}
```
- 脚本路径相对于此 skill 所在的目录。如果仅在回复中返回规范，请先将其写入临时文件，并在回复前对该文件运行脚本。
- 如果脚本以代码
```
1
```
  退出（
```
"status": "FAIL"
```
  ），请修复
```
{spec_file}
```
  中的所有错误，然后再次运行脚本。持续执行，直到脚本以代码
```
0
```
  退出（
```
"status": "PASS"
```
  ）。
- 如果脚本以代码
```
2
```
  退出，请修复文件路径或 stderr 中显示的 YAML/JSON 语法错误，或者安装 PyYAML。
- 阅读每条 warning，例如 backend 缺少
```
pathTranslation
```
  、operation 在没有 API key 的情况下设置配额，或者出现
```
allowCors
```
  。修复这些问题，或者告知用户保留它们的原因。
- 该脚本不会检查所有规则。PASS 表示脚本没有发现此 skill 所描述的任何 API Gateway 问题，但它不会检查一般性的 OpenAPI 有效性，例如
```
$ref
```
  指向不存在的 schema。原因： 只有第 5 步中的
```
api-configs create
```
  才能证明 API Gateway 接受该规范。不要因为脚本通过就告诉用户规范可以部署。
向用户概述规范，并在部署前获得批准。 说明以下各点：
- 移动或删除了哪些 OpenAPI 2.0 extensions，例如 OpenAPI 3.x 不支持的
```
x-google-allow
```
  。同时说明其他每项更改，例如新增
```
operationId
```
  或修复后的地址。
- 每个 backend 的
```
pathTranslation
```
  （脚本输出中的
```
backend_path_translation
```
  ），以及哪些 operations 的 path parameters 现在会作为 query parameters 发送给 backend（
```
path_parameters_as_query
```
  ）。使用
```
APPEND_PATH_TO_ADDRESS
```
  时，backend 还会收到 base path。
- 哪些 operations 需要 JWT 或 API key，哪些 backends 会收到 ID token 及其 audience，并说明 API Gateway 不检查 OAuth scopes。
- 配额 metrics 和 limits，并说明每个 metric name 都与当前 API 配置一致。
创建新的 API 配置并更新 gateway（更新生产 gateway 前需获得人工批准）：
bash
```
gcloud api-gateway api-configs create {new_config_id} \
  --api={api_id} \
  --openapi-spec={spec_file} \
  --backend-auth-service-account={gateway_sa_email} \
  --project={project_id}

gcloud api-gateway gateways update {gateway_id} \
  --api={api_id} \
  --api-config={new_config_id} \
  --location={region} \
  --project={project_id}
```
- 对于新 gateway，请使用相同的 flags 运行
```
gcloud api-gateway gateways create {gateway_id}
```
  ，而不是
```
gateways update
```
  。如果 API 不存在，
```
api-configs create
```
  会创建它。
- 如果某个 operation 需要 API key，请启用该 API 的 managed service。使用
```
gcloud api-gateway apis describe {api_id} --project={project_id} --format="value(managedService)"
```
  获取其名称，然后运行
```
gcloud services enable {managed_service} --project={project_id}
```
  。还应在每个为该 API 创建 API keys 的项目中启用它。
- 每次更改都应使用新的 config ID，因为无法修改现有 API 配置的规范。
- 每个 API 每次只运行一个
```
api-configs create
```
  ，并等待其完成。大型 API 配置的创建时间最长可能达到十分钟。
- 如果
```
api-configs create
```
  失败，请在 API 配置错误中查找错误文本，修复规范，然后返回第 3 步。
- 在新配置开始处理流量之前保留之前的 API 配置。要回滚，请使用之前的 config ID 运行
```
gateways update
```
  。
验证 gateway：
- 运行
```
gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(state,defaultHostname)"
```
  ，并等待状态变为
```
ACTIVE
```
  。
- 使用 operation 所要求的凭据，向
```
https://{default_hostname}{base_path}{path}
```
  中的每个已修改 path 发送请求。检查 backend 是否收到预期的 path 和 parameters。
- HTML
```
404 Page not found
```
  表示 gateway 尚未就绪。检查最后一次 create 或 update 是否已完成，并在修改配置前重试。更新 gateway 期间，部分请求仍可能到达之前的 API 配置。JSON 404（
```
The current request is not defined by this API.
```
  ）表示当前生效的 API 配置未定义该 path。

Pre-Deployment Checklist

部署前检查清单

openapi

3.0.x

3.1.x

, and the spec has no OpenAPI 2.0 extension, such as

x-google-management

x-google-endpoints

x-google-api-name

x-google-allow

, or

x-google-issuer

on a security scheme.

```
x-google-api-management.backends
```
defines every backend, every
```
x-google-backend
```
is a string that names one, and no path item sets
```
x-google-backend
```
.
Every backend sets
```
pathTranslation
```
.
Every operation has a unique
```
operationId
```
and a
```
responses
```
object, and each path variable has a parameter with
```
in: path
```
and
```
required: true
```
.
Every
```
x-google-quota
```
is on an operation that requires an API key, and every metric name matches the current API config.
At most one
```
servers
```
entry has
```
x-google-endpoint
```
, and its URL has no custom port.

python3 scripts/validate_apigw_openapi.py --spec={spec_file}

returns

"status": "PASS"

(exit code

openapi

为

3.0.x

或

3.1.x

，且规范中不存在 OpenAPI 2.0 extension，例如 security scheme 上的

x-google-management

、

x-google-endpoints

、

x-google-api-name

、

x-google-allow

或

x-google-issuer

。

```
x-google-api-management.backends
```
定义了每个 backend，每个
```
x-google-backend
```
都是引用其中某个 backend 的字符串，并且没有 path item 设置
```
x-google-backend
```
。
每个 backend 都设置了
```
pathTranslation
```
。
每个 operation 都有唯一的
```
operationId
```
和
```
responses
```
object，并且每个 path variable 都有一个
```
in: path
```
且
```
required: true
```
的 parameter。
每个
```
x-google-quota
```
都位于要求 API key 的 operation 上，并且每个 metric name 都与当前 API 配置一致。
最多只有一个
```
servers
```
entry 包含
```
x-google-endpoint
```
，并且其 URL 没有自定义端口。

python3 scripts/validate_apigw_openapi.py --spec={spec_file}

"status": "PASS"

（退出代码为

）。

Resource Cleanup

资源清理

To avoid ongoing charges when you tear down a test environment, request human approval, and delete the resources in dependency order:

bash

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}

为避免拆除测试环境后继续产生费用，请先获得人工批准，然后按依赖顺序删除资源：

bash

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}