PHPackages                             lukedavis/gcp-api-gateway-spec - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. lukedavis/gcp-api-gateway-spec

ActiveLibrary[API Development](/categories/api)

lukedavis/gcp-api-gateway-spec
==============================

Generates a Google Cloud API Gateway spec file based on a provided config and a given Swagger 2.0 YAML

v2.0.4(1mo ago)11.4kMITPHPPHP >=8.0CI passing

Since Jul 2Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/dir/gcp-api-gateway-spec)[ Packagist](https://packagist.org/packages/lukedavis/gcp-api-gateway-spec)[ RSS](/packages/lukedavis-gcp-api-gateway-spec/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (10)Dependencies (14)Versions (16)Used By (0)

GCP API Gateway Spec Generator
==============================

[](#gcp-api-gateway-spec-generator)

This is a simple tool that:

- Takes a Swagger 2.0 spec file
- Takes a configuration file
- Generates a new Swagger 2.0 spec file with API Gateway specific properties
- Optionally (recommended), strips responses from the original spec file, and replaces them with generic 200 responses.
    - Complicated responses are a constant source of errors when deploying to the API Gateway, and in most use cases are not necessary.

> The generator does not handle converting API specs (i.e., OpenAPI 3.0 to Swagger 2.0). It is assumed that you have a Swagger 2.0 spec file. If you have an API spec file in a different format, it is recommended to use [api-spec-converter](https://github.com/LucyBot-Inc/api-spec-converter) or another tool to convert it to Swagger 2.0.

The main use case of this tool is an intermediate step in the deployment of an API to Google Cloud Platform's API Gateway. As Google still uses the old Swagger 2.0 spec, and has additional fields that can be added/removed, this tool helps to automate the process of generating a spec file that is compatible with the API Gateway. A common use case for this tool would be on a CI pipeline:

1. Autogenerate spec for your API
2. Convert spec to Swagger 2.0
3. Generate API Gateway spec file
4. Deploy to API Gateway

Installation
------------

[](#installation)

Ensure you have [Composer](https://getcomposer.org/) installed and available in your PATH, as well as PHP 8.0 or later.

> **Note for PHP 8.0:** every symfony/yaml version installable on PHP 8.0 carries known (low-severity) security advisories — the 6.x line was only patched in 6.4, which requires PHP 8.1. Composer ≥ 2.9 therefore blocks resolution on PHP 8.0 by default; you would need to opt out via `config.audit.block-insecure: false` (at your own risk). On PHP 8.1+ this does not apply.

### Local

[](#local)

Run the following command in your project root:

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

After installing, you can now run the tool using: `./vendor/bin/gcp-api-gateway-spec generate` from your project root.

### Global

[](#global)

Run the following command anywhere in your terminal:

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

After installing, the tool will now be in your composer installation's bin directory at `/vendor/bin/gcp-api-gateway-spec`.

You can view the path to your composer's home directory by running `composer -n config --global home`.

> You can alias the path to the tool or add the composer vendor/bin directory to your PATH in your `.zshrc` or `.bashrc` for easier access.

Usage
-----

[](#usage)

### Requirements

[](#requirements)

- Swagger 2.0 YAML spec file, passed as the first argument to `generate`
    - If you are working with an OpenAPI 3.0 spec file, I recommend using [api-spec-converter](https://github.com/LucyBot-Inc/api-spec-converter) to create a Swagger 2.0 spec file.
- Configuration file (see [Configuration](#configuration))

### Command

[](#command)

```
gcp-api-gateway-spec generate swagger2.yaml \
  --output=api-gateway.yaml \
  --config=config.yaml \
  [--host=api.example.com] \
  [--backend=https://backend.example.com] \
  [--preserve-responses]
```

Argument / optionDescription`input` (argument)Path to the input Swagger 2.0 YAML spec file. Required.`--output`, `-o`Where to write the generated spec. See [Output path resolution](#output-path-resolution).`--config`, `-c`Path to the config file. Required.`--host`Sets the top-level `host` of the generated spec. Optional.`--backend`, `-b`Sets `x-google-backend.address` at the top level and on every operation. Optional.`--preserve-responses`, `-p`Keep the response schemas from the input spec. By default responses are replaced with a generic 200.### Output path resolution

[](#output-path-resolution)

- **Absolute path** (e.g. `--output=/tmp/specs/api-gateway.yaml`): used as-is. Missing directories are created.
- **Relative path** (e.g. `--output=build/api-gateway.yaml`): resolved against the current working directory.
- **Directory** (existing): the file is written inside it as `generator-output.yaml`.
- **Omitted**: writes `generator-output.yaml` in the current working directory.

### Examples

[](#examples)

Absolute path with filename:

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

With `--preserve-responses` and a relative output to cwd:

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

Configuration
-------------

[](#configuration)

Values in the config file take precedence over the corresponding values in the input spec (`info`, `basePath`, `produces`, `consumes`, `securityDefinitions`, `x-google-backend`). Take a look at the [example config](config.example.yaml) for a practical example.

```
# Optional; taken from the input spec if not set here
info:
  title: My API
  version: "1.0.0"

# Optional, defaults to /
basePath: /v1

# Optional, defaults to application/json
produces:
  - application/json
consumes:
  - application/json

# Define your security definitions here
securityDefinitions:
  auth0:
    authorizationUrl: 'https://example.auth0.com/authorize'
    flow: implicit
    type: oauth2
    x-google-issuer: 'https://example.auth0.com/'
    x-google-jwks_uri: 'https://example.auth0.com/.well-known/jwks.json'
    x-google-audiences: 'https://example.com'

# Top-level x-google-backend (the --backend option overrides its address)
x-google-backend:
  path_translation: 'APPEND_PATH_TO_ADDRESS'

# Default configuration applied to every operation if not overridden
# Useful for setting global security definitions
path-defaults:
  security:
    - auth0: []
  x-google-backend:
    path_translation: 'APPEND_PATH_TO_ADDRESS'

# Path/method specific overrides
# Useful for removing security from specific paths
path-overrides:
  /unsecured-route:
    post:
      consumes:
        - multipart/form-data
      security: []
    get:
      security: []
```

For each operation, the effective spec starts from `path-defaults`, with same-named keys replaced wholesale by the matching `path-overrides..` entry; the operation from the input spec is then merged in recursively, winning per key (and per index for lists). Note this means an override such as `security: []` cannot remove a `security` list the input spec itself defines — the input's entries win index-wise. It does work for the common case where security comes from `path-defaults`.

Normalization
-------------

[](#normalization)

Besides merging the config, the generator applies a few normalizations so that the output passes the API Gateway's Swagger 2.0 validation:

- **Responses** are replaced with a generic `200` response unless `--preserve-responses` is passed. Empty `responses` maps are replaced with the generic response as well.
- **Path parameters** that appear in a path template (e.g. `/pets/{petId}`) but are not declared on the operation are added as required string parameters.
- **Nullable types** are rewritten: `type: "null"` becomes `type: string` with `x-nullable: true`. A `type` list collapses to its first non-`"null"` entry (so `type: [string, "null"]` becomes `type: string` with `x-nullable: true`, and a multi-type list like `type: [string, integer]` becomes `type: string`). Properties literally named `type`, and map-valued `type` keys inside free-form data (`examples`, `default`, `enum` values, `x-` extensions), are left untouched.
- **Unsupported JSON Schema keywords** are removed: `additionalItems`, `patternProperties`, `dependencies`, `propertyNames`, `contains`, `const`, `if`, `then`, `else`.
- **Empty schemas** (e.g. `nickname: {}`, common in specs converted with api-spec-converter) are kept as empty objects instead of degrading to `[]`, which the API Gateway validator rejects. Empty sequences such as `security: []` are unaffected.

Development
-----------

[](#development)

```
composer install
vendor/bin/phpunit             # tests (golden files + schema validation)
vendor/bin/phpstan analyse     # static analysis
vendor/bin/php-cs-fixer fix    # code style
```

Generated output is byte-compared against golden files in `tests/fixtures/cases/*/expected.yaml` and validated against the official Swagger 2.0 JSON schema — the same validation `gcloud api-gateway api-configs create` performs. After an intentional output change, regenerate goldens with `UPDATE_GOLDENS=1 vendor/bin/phpunit`.

Disclaimer
----------

[](#disclaimer)

This tool is not officially supported by Google Cloud Platform or the API Gateway team.

This tool is provided as-is and without warranties of any kind. Luke Davis is not responsible for any security issues, vulnerabilities, or other problems that may arise from the use of this tool.

Users are responsible for ensuring the security and suitability of this tool for their specific needs and use cases. Use at your own risk.

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance91

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~52 days

Recently: every ~134 days

Total

15

Last Release

42d ago

Major Versions

v1.2.9 → v2.0.02025-01-18

PHP version history (2 changes)1.0.0PHP >=8.1

v1.2.7PHP >=8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/505864?v=4)[lke](/maintainers/lke)[@LKE](https://github.com/LKE)

---

Top Contributors

[![dir](https://avatars.githubusercontent.com/u/6627316?v=4)](https://github.com/dir "dir (32 commits)")

---

Tags

apigoogleopenapigatewaygcpoas

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/lukedavis-gcp-api-gateway-spec/health.svg)

```
[![Health](https://phpackages.com/badges/lukedavis-gcp-api-gateway-spec/health.svg)](https://phpackages.com/packages/lukedavis-gcp-api-gateway-spec)
```

###  Alternatives

[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19467.3M1.9k](/packages/drupal-core)[kimai/kimai

Kimai - Time Tracking

4.8k9.4k1](/packages/kimai-kimai)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.9M535](/packages/pimcore-pimcore)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.8M674](/packages/shopware-core)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)