README

这是一个简单的工具，

• 接收Swagger 2.0规范文件
• 接收配置文件
• 生成新的Swagger 2.0规范文件，具有API网关特定属性
• 可选（推荐），从原始规范文件中删除响应，并用通用的200响应替换。

  • 复杂的响应在部署到API网关时是错误的一个常见来源，在大多数情况下并不必要。

生成器不处理API规范（即，OpenAPI 3.0到Swagger 2.0）的转换。假设您有一个Swagger 2.0规范文件。如果您有不同的格式的API规范文件，建议使用api-spec-converter或其他工具将其转换为Swagger 2.0。

此工具的主要用例是将API部署到Google Cloud Platform的API网关的中间步骤。由于Google仍然使用旧的Swagger 2.0规范，并且还可能有可添加/删除的额外字段，因此此工具有助于自动化生成与API网关兼容的规范文件的过程。此工具的常见用例包括

CI流水线

1. 自动生成API的规范
2. 将规范转换为Swagger 2.0
3. 生成API网关规范文件
4. 部署到API网关

免责声明

此工具不是由Google Cloud Platform或API网关团队官方支持的。

此工具按现状提供，不提供任何类型的保证。Luke Davis不对由此工具使用而引起的任何安全问题、漏洞或其他问题负责。

用户负责确保此工具符合其特定需求和用例的安全性。自行承担风险。

安装

确保您已安装Composer并在PATH中可用，以及PHP 8.1或更高版本。

本地

在项目根目录中运行以下命令

composer require lukedavis/gcp-api-gateway-spec --dev

安装后，您现在可以从项目根目录使用以下命令运行工具：./vendor/bin/gcp-api-gateway-spec generate。

全局

在任何终端中运行以下命令

composer global require lukedavis/gcp-api-gateway-spec

安装后，工具现在位于您的composer安装的bin目录中，路径为 <composer-home>/vendor/bin/gcp-api-gateway-spec。

您可以通过运行 composer -n config --global home 来查看您的composer主目录的路径。

您可以将工具的路径设置为别名，或将composer vendor/bin目录添加到您的 .zshrc 或 .bashrc 中，以便更容易访问。

配置

以下是一些配置选项，请参阅 config.example.yaml 文件以获取更实际的示例。

# Define your security definitions here
securityDefinitions: []

# Default configuration applied to all paths if not overridden
# Useful for setting global security definitions
path-defaults:
  security: []

# Path/method specific overrides
# Useful for setting security definitions on specific paths
path-overrides: []

用法

要求

• Swagger 2.0 YAML规范文件
  • 如果您正在使用OpenAPI 3.0规范文件，我建议使用 api-spec-converter 创建Swagger 2.0规范文件。
• 配置文件（见config.example.yaml）
• 输出
  • 可以是绝对路径、相对路径或加一个文件名。如果没有提供文件名，生成的文件将命名为 generator-output.yaml。

命令

gcp-api-gateway-spec generate \
  --input=swagger.yaml \
  --output=api-gateway.yaml \
  --config=config.yaml \
  [--preserve-responses]

示例

绝对路径加文件名

gcp-api-gateway-spec generate \
    --input=swagger.yaml \
    --output=/tmp/api-gateway.yaml \
    --config=config.yaml

使用 --preserve-responses 标志和相对输出到当前工作目录

gcp-api-gateway-spec generate \
    --input=swagger.yaml \
    --output=api-gateway.yaml
    --config=config.yaml \
    --preserve-responses