Mock OpenAPI Description

You can use the mock oas command to create a mock API proxy from your OpenAPI 3 Description, allowing you to simulate API behavior without a real backend.

Examples

Below are a couple example of how to use the mock oas command

Create bundle zip

apigee-go-gen mock oas \
    --input ./examples/specs/oas3/petstore.yaml \
    --output ./out/mock-apiproxies/petstore.zip

Create bundle dir

apigee-go-gen mock oas \
    --input ./examples/specs/oas3/petstore.yaml \
    --output ./out/mock-apiproxies/petstore

Mock API Proxy Features

The generated mock API proxy supports the following features.

Base Path from OAS Description

The Base Path for the mock API proxy is derived from the first element of the servers array in your OpenAPI Description.

For example, if your server array looks like this:

servers:
  - url: https://petstore.swagger.io/v3
  - url: https://petstore.swagger.io/staging/v3

The mock API proxy Base Path will be /v3

CORS Support

The generated mock API proxy includes the Apigee CORS policy, making it easy to test your API from various browser-based clients.

Here's how it works:

Automatic CORS Headers: The proxy automatically adds the necessary CORS headers (like Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc.) to all responses.
Preflight Requests: The proxy correctly handles preflight OPTIONS requests, responding with the appropriate CORS headers to indicate allowed origins, methods, and headers.
Permissive Configuration: By default, the CORS policy is configured to be as permissive as possible, allowing requests from any origin with any HTTP method and headers. This maximizes flexibility for your testing.

This built-in CORS support ensures that your mock API behaves like a real API in a browser environment, simplifying your development and testing workflow.

Request Validation

By default, the mock API proxy validates the incoming requests against your description. This ensures that the HTTP headers, query parameters, and request body all conform to the defined rules.

This helps you catch errors in your client code early on.

You can disable request validation by passing the header:

Mock-Validate-Request: false

Dynamic Response Status Code

The mock API proxy automatically generates different status codes for your mock API responses. Here's how it works:

Prioritizes success: If the operation allows HTTP 200 status code, the proxy will use it.
Random selection: If HTTP 200 is not allowed for a particular operation, the proxy will pick a random status code from those allowed.

Want more control? You can use headers to select response the status code:

Specific status code: Use the Mock-Status header in your request and set it to the desired code (e.g., Mock-Status: 404).
Random status code: Use the Mock-Fuzz: true header to get a random status code from your description.

If you use both Mock-Status and Mock-Fuzz, Mock-Status takes precedence.

Dynamic Response Content-Type

The mock API proxy automatically selects the Content-Type for responses:

JSON preferred: If the operation allows application/json, the proxy will default to using it.
Random selection: If application/json is not available, the proxy will randomly choose from the media types available for that operation.

Want more control? You can use headers to select the response Content-Type:

Standard Accept header: You can use the standard Accept header in your request to request a specific media type (e.g., Accept: application/xml).
Random media type: Alternatively, use the Mock-Fuzz: true header to have the proxy select a random media type the available ones.

If you use both Accept and Mock-Fuzz, the Accept header will take precedence.

Dynamic Response Body

The mock API proxy can generate realistic response bodies based on your OpenAPI Description.

Here's how it determines what to send back for any particular operation's response (in order):

Prioritizes example field: If the response includes an example field, the proxy will use that example.
Handles multiple examples: If the response has an examples field with multiple examples, the proxy will randomly select one. You can use the Mock-Example header to specify which example you want (e.g., Mock-Example: my-example).
Uses schema examples: If no response examples are provided, but the schema for the response has an example, the proxy will use that.
Generates from schema: As a last resort, the proxy will generate a random example based on the response schema. This works for JSON, YAML, and XML.

You can use the Mock-Fuzz: true header to force the proxy to always generate a random example from the schema, even if other static examples are available.

AI-Powered Mock Responses

For more realistic and contextually rich response bodies, you can enable integration with Google's Gemini model. This can be done via a Google Cloud Vertex AI endpoint or the public Gemini API endpoint.

When enabled, and if a static example is not available, the mock proxy will call the Gemini model with your response schema (for JSON/XML) and ask it to generate a plausible mock payload based on semantic understanding of the schema's properties and descriptions.

Option 1: Enabling via Vertex AI API Endpoint

Flag	Description	Required
`--set vertex.enabled=true`	Activates Vertex AI generation for the mock proxy.	Yes
`--set vertex.project_id=<project>`	The ID of the Google Cloud project hosting the Vertex AI endpoint.	Yes
`--set vertex.region=<region>`	The GCP region where the Vertex AI endpoint is located. (defaults to `us-central1`)	No
`--set vertex.model=<model>`	The Gemini model to use for generation (defaults to `gemini-2.5-flash`).	No

Example (Vertex AI):

apigee-go-gen mock oas \
    --input ./examples/specs/oas3/petstore.yaml \
    --output ./out/mock-apiproxies/petstore.zip \
    --set vertex.enabled=true \
    --set vertex.project_id=my-gcp-project

Note: The service account used to deploy the API proxy must have the necessary permissions (e.g., Vertex AI User role) to call the Vertex AI API endpoint.

Option 2: Enabling via Public Gemini API Endpoint

Flag	Description	Required
`--set gemini.enabled=true`	Activates public Gemini API generation.	Yes
`--set gemini.api_key=<key>`	Your public Gemini API key.	Yes
`--set gemini.model=<model>`	The Gemini model to use (defaults to `gemini-2.5-flash`).	No

Example (Gemini API):

apigee-go-gen mock oas \
    --input ./examples/specs/oas3/petstore.yaml \
    --output ./out/mock-apiproxies/petstore.zip \
    --set gemini.enabled=true \
    --set gemini.api_key=AIza...

Supported Media Types for AI Generation

The Gemini model is explicitly used for:

JSON (application/json)
XML (application/xml or related types)

If the response media type is anything else (e.g., text/plain), the proxy falls back to its built-in legacy schema fuzzer.

Repeatable API Responses

The mock API proxy uses a special technique to make its responses seem random, while still allowing you to get the same response again if needed. Here's how it works:

Pseudo-random numbers: The "random" choices the proxy makes (like status codes and content) are actually generated using a pseudo-random number generator (PRNG). This means the responses look random, but are determined by a starting value called a "seed."
Unique seeds: Each request uses a different seed, so responses vary. However, the seed is provided in a special response header called Mock-Seed.
Getting the same response: To get an identical response, simply include the Mock-Seed header in a new request, using the value from a previous response. This forces the proxy to use the same seed and generate the same "random" choices, resulting in an identical response.

This feature is super helpful for:

Testing: Ensuring your tests always get the same response.
Debugging: Easily recreating specific scenarios to pinpoint issues in application code.

Essentially, by using the Mock-Seed header, you can control the randomness of the mock API responses, making them repeatable for testing and debugging.

Example Generation from JSON Schemas

The following fields are supported when generating examples from a JSON schema:

$ref - local references are followed
$oneOf - chooses a random schema
$anyOf - chooses a random schema
$allOf - combines all schemas
object type
- required field - all required properties are chosen
- properties field - a random set of properties is chosen
- additionalProperties field - only used when there are no properties defined
array type
- minItems, maxItems fields - array length chosen randomly between these values
- items field - determines the type of array elements
- prefixItems (not supported yet)
null type
const type
boolean type - true or false randomly chosen
string type
- enum field - a random value is chosen from the list
- pattern field (not supported yet)
- format field
  - date-time format
  - date format
  - time format
  - email format
  - uuid format
  - uri format
  - hostname format
  - ipv4 format
  - ipv6 format
  - duration format
- minLength, maxLength fields - string length chosen randomly between these values
integer type
- minimum, maximum fields - a random integer value chosen randomly between these values
- exclusiveMinimum field (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
- exclusiveMaximum field (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
- multipleOf field
number type
- minimum, maximum fields - a random float value chosen randomly between these values
- exclusiveMinimum field (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
- exclusiveMaximum field (boolean, JSON-Schema 4, number, JSON Schema 7 or greater)
- multipleOf field

Markdown

Enriching your OpenAPI Description with Examples

Sometimes, your OpenAPI Description might be missing response examples or schemas. In other cases, the examples might be very large and difficult to include directly in the description. Overlays provide a solution for these situations.

What is an Overlay?

An Overlay is a separate file that allows you to add or modify information in your existing OpenAPI Description. This is useful for adding examples, schemas, or any other data that you want to keep separate from your main description file. To learn more about how Overlays work, you can refer to the Overlay Specification.

How to use an Overlay

Here's how you can use an Overlay to add a static example to an API operation:

Create an Overlay file: This file defines the changes you want to make to your OpenAPI Description. Here's an example that adds a sample response for the /pet/findByStatus operation:

overlay: 1.0.0
info:
  title: Add example response JSON for GET /get/findByStatus
  version: 1.0.0
actions:
  - target: $.paths./pet/findByStatus.get.responses.200
    update:
      content:
        'application/json':
          examples:
            findByStatus:
              value:
                {
                  "id": 1,
                  "photoUrls": [],
                  "name": "Rin Tin Tin",
                  "category": {
                    "id": 1,
                    "name": "Dog"
                  }
                }

Apply the Overlay to your OpenAPI Description: Use the apigee-go-gen tool to combine your Overlay file with your OpenAPI Description:

apigee-go-gen transform oas-overlay \
  --spec ./examples/specs/oas3/petstore.yaml \
  --overlay ./examples/overlays/petstore-dog-example.yaml \
  --output ./out/specs/petstore-overlaid.yaml

Generate a mock API proxy: You can now use the updated OpenAPI Description to generate a mock API proxy in Apigee:

apigee-go-gen mock oas \
    --input ./out/specs/petstore-overlaid.yaml \
    --output ./out/mock-apiproxies/petstore.zip

This process allows you to manage your OpenAPI Description more effectively by keeping your examples and other supplementary data in separate files.