### Complete YAML Configuration Example

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/distribution-settings.md

A comprehensive example demonstrating the structure of the generator configuration, including test generation budgets, security values, and example providers.

```yaml
specFile: "src/test/resources/openapi.yaml"
outputDir: "./build/generated/openapi-tests"
generator: "template"
generatorOptions:
    templateSet: restassured-java
    templateVariables:
        package: com.example.generated
        baseUrl: http://localhost:8080

testGenerationSettings:
    # Budget controls
    maxSchemaDepth: 50
    maxMergedSchemaDepth: 50
    maxSchemaCombinations: 100
    maxTestCasesPerOperation: 1000
    maxErrors: 100
    errorMode: COLLECT_ALL

    # Security
    validSecurityValues:
        ApiKeyAuth: "test-api-key"
        BearerAuth: "Bearer test-token"

    # Ignore configuration
    ignoreTestCases:
        "/health": "*"
    ignoreSchemaValidationRules: [ ]
    ignoreAuthValidationRules: [ ]

    # Example value settings
    exampleValues:
        providers:
            - enum
            - const
            - uuid
            - email
            - date
            - date-time
            - pattern
            - plain-string
            - number
            - boolean
        maxExampleDepth: 50

    # Pattern generation (from pattern-support module)
    patternGeneration:
        defaultMinLength: 3

alwaysWriteTests: false
logLevel: INFO
```

--------------------------------

### Install @openapi-testgen/cli-linux-x64

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/npm/cli-linux-x64/README.md

Use this command for standalone installation of the Linux x64 binary.

```bash
npm install -g @openapi-testgen/cli-linux-x64
```

--------------------------------

### Example Generation Configuration

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/distribution-settings.md

A comprehensive example showing custom provider ordering, depth limits, and provider-specific templates.

```yaml
testGenerationSettings:
    exampleValues:
        providers:
            - enum
            - const
            - pattern
            - plain-string
        maxExampleDepth: 15
        includeOptionalExampleProperties: true
        includeWriteOnly: false
        useSchemaExampleFallback: true
        fullExample: true
        uuid:
            template: "test-uuid-%s"
        email:
            template: "test%s@myapp.com"
        date:
            startDate: "2024-01-01"
```

--------------------------------

### Install CLI globally

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/npm/cli-win32-x64/README.md

Use this command to install the Windows x64 binary package globally on your system.

```bash
npm install -g @openapi-testgen/cli-win32-x64
```

--------------------------------

### Apply and configure the plugin

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/gradle-plugin.md

A complete example of applying and configuring the plugin in a build script.

```kotlin
plugins {
    id("art.galushko.openapi-test-generator") version "<version>"
}

openApiTestGenerator {
    specFile.set("src/test/resources/openapi.yaml")
    outputDir.set(layout.buildDirectory.dir("generated/openapi-tests"))
    generator.set("template")
}
```

--------------------------------

### Install @openapi-testgen/cli-linux-arm64

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/npm/cli-linux-arm64/README.md

Use this command for standalone installation of the native Linux ARM64 binary.

```bash
npm install -g @openapi-testgen/cli-linux-arm64
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/documentation-guide.md

Install the necessary Python dependencies for local documentation preview using pip.

```bash
python -m pip install -r requirements.txt
```

--------------------------------

### Check Java version and install

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/troubleshooting.md

Verify the installed Java version and install Java 21 on various operating systems to support JAR-based execution.

```bash
# Check Java version
java -version

# Install Java 21
# Ubuntu/Debian
sudo apt install openjdk-21-jre

# macOS (Homebrew)
brew install openjdk@21

# Windows (Chocolatey)
choco install temurin21
```

--------------------------------

### Install OpenAPI Test Generator CLI Globally

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/cli/README.md

Installs the CLI globally using npm. This is the recommended installation method for easy access.

```bash
npm install -g @openapi-testgen/cli
```

--------------------------------

### Install CLI via npm package managers

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/getting-started/installation.md

Global installation commands for various Node.js package managers.

```bash
npm install -g @openapi-testgen/cli
openapi-testgen --help
```

```bash
pnpm add -g @openapi-testgen/cli
pnpm dlx @openapi-testgen/cli --help
```

```bash
yarn global add @openapi-testgen/cli
yarn dlx @openapi-testgen/cli --help
```

```bash
bun add -g @openapi-testgen/cli
bunx @openapi-testgen/cli --help
```

--------------------------------

### Build from source

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/getting-started/installation.md

Gradle commands to build the CLI as an installable distribution, fat JAR, or native image.

```bash
# Installable JVM distribution
./gradlew :cli:installDist
./cli/build/install/openapi-testgen/bin/openapi-testgen --help

# Fat JAR
./gradlew :cli:shadowJar
java -jar cli/build/libs/openapi-testgen-*-all.jar --help

# Native image (requires GraalVM)
./gradlew :cli:nativeCompile
./cli/build/native/nativeCompile/openapi-testgen --help
```

--------------------------------

### Start Verdaccio Local Registry

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/npm-publishing.md

Starts a Verdaccio local npm registry using Docker. This is useful for testing the full installation flow locally before publishing to the public npm registry.

```bash
# Start Verdaccio
docker run -d -p 4873:4873 --name verdaccio verdaccio/verdaccio

# Configure npm to use local registry
npm config set registry http://localhost:4873
npm config set //localhost:4873/:_authToken "test-token"

# Publish packages
cd cli/build/npm
for pkg in cli-linux-x64 cli-linux-arm64 cli-darwin-arm64 cli-win32-x64 cli; do
  if [[ -d "$pkg" ]]; then
    cd "$pkg" && npm publish --access public && cd ..
  fi
done

# Test installation
npm install -g @openapi-testgen/cli --registry http://localhost:4873
openapi-testgen --version

# Cleanup
npm config delete registry
npm config delete //localhost:4873/:_authToken
docker stop verdaccio && docker rm verdaccio

```

--------------------------------

### Install @openapi-testgen/cli

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/npm/cli/README.md

Commands for installing the CLI globally, running via npx, or adding as a project dependency.

```bash
# Global installation
npm install -g @openapi-testgen/cli

# Run directly with npx
npx @openapi-testgen/cli --help

# Project dependency
npm install --save-dev @openapi-testgen/cli
```

--------------------------------

### Analyzing Test Case Distribution Example

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/model.md

Command-line examples using `jq` to analyze test cases based on their generating rule.

```APIDOC
## Analyzing Test Case Distribution

### Description
Examples using the `jq` command-line tool to inspect and count test cases generated by specific rules or providers.

### Examples

**Find test cases by rule:**
```bash
jq '.[] | .testCases[] | select(.rule == "art.galushko.openapi.testgen.rules.schema.InvalidEnumValueSchemaValidationRule")' \
  generated/test-suites.json
```

**Find test cases by provider:**
```bash
jq '.[] | .testCases[] | select(.rule == "art.galushko.openapi.testgen.providers.parameter.MissedRequiredParameterTestProvider")' \
  generated/test-suites.json
```

**Count test cases per rule:**
```bash
jq '[.[] | .testCases[].rule] | group_by(.) | map({rule: .[0], count: length})' \
  generated/test-suites.json
```
```

--------------------------------

### Configure example values and parser settings

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/gradle-plugin.md

Customize test generation behavior and parser limits using the nested DSL blocks.

```kotlin
openApiTestGenerator {
    testGenerationSettings {
        exampleValues.putAll(
            mapOf(
                "includeOptionalExampleProperties" to true,
                "includeWriteOnly" to false,
                "useSchemaExampleFallback" to true,
                "fullExample" to true,
            )
        )
    }
    parserSettings {
        yamlCodePointLimit.set(10_000_000)
    }
}
```

--------------------------------

### CLI and Gradle Configuration Execution

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/configuration.md

Examples of how to trigger test generation using the CLI or Gradle plugin with a configuration file.

```bash
openapi-testgen \
  --config-file ./openapi-testgen.yaml \
  --spec-file ./src/test/resources/openapi.yaml
```

```kotlin
openApiTestGenerator {
    configFile.set("openapi-testgen.yaml")
}
```

--------------------------------

### Include Multiple Paths and Methods

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/configuration.md

Configure `includeOperations` to include tests for multiple distinct API paths and their associated HTTP methods. This example includes GET for `/users/{userId}` and POST for `/orders`.

```yaml
testGenerationSettings:
  includeOperations:
    "/users/{userId}": ["GET"]
    "/orders": ["POST"]
```

--------------------------------

### Configure native package metadata

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/npm-publishing.md

Example package.json configuration for native binary packages, specifying platform, CPU, and libc compatibility.

```json
{
    "name": "@openapi-testgen/cli-linux-x64",
    "os": [
        "linux"
    ],
    "cpu": [
        "x64"
    ],
    "libc": [
        "glibc"
    ],
    "bin": {
        "openapi-testgen": "./bin/openapi-testgen"
    },
    "files": [
        "bin/"
    ]
}
```

--------------------------------

### Example OpenAPI Specification

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/README.md

A sample OpenAPI specification defining a GET /users endpoint with a 'page' query parameter that must be an integer with a minimum value of 1.

```yaml
paths:
  /users:
    get:
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
```

--------------------------------

### Install @openapi-testgen/cli-darwin-arm64 Globally

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/npm/cli-darwin-arm64/README.md

Use this command to install the package globally. Ensure Node.js 18+ and macOS 11+ are prerequisites.

```bash
npm install -g @openapi-testgen/cli-darwin-arm64
```

--------------------------------

### Configuration Methods

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/generators.md

Examples of how to configure the OpenAPI Test Generator using Gradle, CLI, or a YAML configuration file.

```APIDOC
## Configuration Methods

### Gradle
```kotlin
openApiTestGenerator {
    specFile.set("openapi.yaml")
    outputDir.set(layout.projectDirectory.dir("src/test/kotlin/generated"))
    generator.set("template")
    generatorOptions.putAll(
        mapOf(
            "templateSet" to "restassured-kotlin",
            "customTemplateDir" to "templates",
            "classTemplatePath" to "class.mustache",
            "outputFileExtension" to "kt",
            "templateVariables" to mapOf(
                "package" to "com.example.generated",
                "baseUrl" to "http://localhost:8080/v1",
                "springBootTest" to "true",
            ),
        )
    )
}
```

### CLI
```bash
openapi-testgen \
  --spec-file openapi.yaml \
  --output-dir ./generated \
  --generator template \
  --generator-option customTemplateDir=./templates \
  --generator-option classTemplatePath=class.mustache \
  --generator-option outputFileExtension=kt \
  --generator-option templateVariables.package=com.example.generated \
  --generator-option templateVariables.baseUrl=http://localhost:8080
```

### YAML
```yaml
generator: template
generatorOptions:
    customTemplateDir: "./templates"
    classTemplatePath: "class.mustache"
    outputFileExtension: "kt"
    templateVariables:
        package: "com.example.generated"
        baseUrl: "http://localhost:8080/v1"
        springBootTest: "true"
```
```

--------------------------------

### Configure main package metadata

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/npm-publishing.md

Example package.json configuration for the main CLI package, including binary mapping and optional dependencies for native binaries.

```json
{
    "name": "@openapi-testgen/cli",
    "bin": {
        "openapi-testgen": "./bin/openapi-testgen"
    },
    "files": [
        "bin/",
        "lib/",
        "scripts/"
    ],
    "engines": {
        "node": ">=18.0.0"
    },
    "optionalDependencies": {
        "@openapi-testgen/cli-linux-x64": "X.Y.Z",
        "@openapi-testgen/cli-linux-arm64": "X.Y.Z",
        "@openapi-testgen/cli-darwin-arm64": "X.Y.Z",
        "@openapi-testgen/cli-win32-x64": "X.Y.Z"
    }
}
```

--------------------------------

### Install CLI in CI

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/ci-cd.md

Commands for invoking the CLI tool in CI environments, either via npx or global npm installation.

```bash
npx @openapi-testgen/cli --help
```

```bash
npm install -g @openapi-testgen/cli
openapi-testgen --version
```

--------------------------------

### Example `test-suite-writer` Output

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/getting-started/index.md

An example of the JSON output generated by the `test-suite-writer`. It shows test cases for a `getUser` operation, including invalid path parameters and missing security values, with expected status codes.

```json
{
    "getUser": {
        "path": "/users/{userId}",
        "method": "GET",
        "operationName": "getUser",
        "testCases": [
            {
                "name": "Invalid Path userId parameter: Invalid Pattern",
                "method": "GET",
                "path": "/users/{userId}",
                "pathParams": { "userId": "AE." },
                "headers": [{ "key": "X-API-Key", "value": "test-api-key-123" }],
                "expectedStatusCode": 400
            },
            {
                "name": "No security values provided",
                "method": "GET",
                "path": "/users/{userId}",
                "headers": [],
                "expectedStatusCode": 401
            }
        ]
    }
}
```

--------------------------------

### Install Java on Alpine Linux

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/troubleshooting.md

Install Java 21 on musl-based systems like Alpine Linux to support the JAR fallback.

```bash
apk add openjdk21
```

--------------------------------

### Configure example value generation settings

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/cli.md

Adjusts test generation behavior regarding optional properties and schema fallbacks.

```bash
openapi-testgen \
  --spec-file ./openapi.yaml \
  --output-dir ./build/generated-tests \
  --generator template \
  --setting exampleValues.includeOptionalExampleProperties=true \
  --setting exampleValues.includeWriteOnly=false \
  --setting exampleValues.useSchemaExampleFallback=true \
  --setting exampleValues.fullExample=true
```

--------------------------------

### Install OpenAPI Test Generator CLI

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/README.md

Install the OpenAPI Test Generator CLI globally using npm. This command also provides access to the help documentation.

```bash
npm install -g @openapi-testgen/cli
openapi-testgen --help
```

--------------------------------

### Build CLI Distribution with Gradle

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/README.md

Use this command to build the command-line interface distribution of the project. Requires Gradle to be installed.

```bash
./gradlew :cli:installDist
```

--------------------------------

### Configure OpenAPI Test Generator

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/generators.md

Configuration examples for the generator using different interfaces.

```kotlin
openApiTestGenerator {
    specFile.set("openapi.yaml")
    outputDir.set(layout.projectDirectory.dir("src/test/kotlin/generated"))
    generator.set("template")
    generatorOptions.putAll(
        mapOf(
            "templateSet" to "restassured-kotlin",
            "customTemplateDir" to "templates",
            "classTemplatePath" to "class.mustache",
            "outputFileExtension" to "kt",
            "templateVariables" to mapOf(
                "package" to "com.example.generated",
                "baseUrl" to "http://localhost:8080/v1",
                "springBootTest" to "true",
            ),
        )
    )
}
```

```bash
openapi-testgen \
  --spec-file openapi.yaml \
  --output-dir ./generated \
  --generator template \
  --generator-option customTemplateDir=./templates \
  --generator-option classTemplatePath=class.mustache \
  --generator-option outputFileExtension=kt \
  --generator-option templateVariables.package=com.example.generated \
  --generator-option templateVariables.baseUrl=http://localhost:8080
```

```yaml
generator: template
generatorOptions:
    customTemplateDir: "./templates"
    classTemplatePath: "class.mustache"
    outputFileExtension: "kt"
    templateVariables:
        package: "com.example.generated"
        baseUrl: "http://localhost:8080/v1"
        springBootTest: "true"
```

--------------------------------

### Configure Alpine Linux for CLI

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/getting-started/installation.md

Install Java 21 on Alpine Linux to support the JAR fallback mechanism.

```bash
npm install -g @openapi-testgen/cli
apk add openjdk21
```

--------------------------------

### Initialize Test Generation Engine with Pattern Support

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/pattern-support/README.md

Manually wire the PatternSupportModule and PatternModuleSettingsExtractor into the TestGenerationEngine for custom setups.

```kotlin
val engine = TestGenerationEngine(
    modules = listOf(PatternSupportModule()),
    settingsExtractors = listOf(PatternModuleSettingsExtractor()),
    testGenerationSettings = settings
)
```

--------------------------------

### Example OpenAPI Path Definition

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/negative-testing.md

Defines a POST endpoint for creating orders with a request body schema reference.

```yaml
paths:
    /orders:
        post:
            operationId: createOrder
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NewOrder'
```

--------------------------------

### Generate test suites via CLI

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/ci-cd.md

Use npx to execute the CLI generator without requiring a global installation.

```bash
npx @openapi-testgen/cli \
  --spec-file ./openapi.yaml \
  --output-dir ./generated \
  --generator test-suite-writer \
  --generator-option format=json \
  --generator-option outputFileName=test-suites.json
```

--------------------------------

### Example OpenAPI Schema Definitions

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/negative-testing.md

Defines schemas for OrderItem and NewOrder, including required properties and constraints.

```yaml
components:
    schemas:
        OrderItem:
            type: object
            required: [ sku, quantity, price ]
            additionalProperties: false
            properties:
                sku: { type: string }
                quantity: { type: integer, minimum: 1 }
                price: { type: number, minimum: 0 }
        NewOrder:
            type: object
            required: [ userId, items ]
            additionalProperties: false
            properties:
                userId: { type: string }
                items:
                    type: array
                    minItems: 1
                    items: { $ref: '#/components/schemas/OrderItem' }
```

--------------------------------

### Configure Included Operations in Gradle

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/configuration.md

Use `includeOperations` within the `testGenerationSettings` block in your Gradle build file to specify which API operations should have tests generated. This example includes the GET method for the `/users/{userId}` path.

```kotlin
openApiTestGenerator {
    // ... specFile, outputDir, generator, generatorOptions ...
    testGenerationSettings {
        includeOperations.putAll(
            mapOf(
                "/users/{userId}" to listOf("GET")
            )
        )
    }
}
```

--------------------------------

### Serve Documentation Locally with Gradle

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/documentation-guide.md

Serve the documentation locally using the gradlew command. This command also regenerates Dokka output.

```bash
./gradlew docsServe
```

--------------------------------

### Combine IncludeOperations and IgnoreTestCases

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/configuration.md

Demonstrates how to use both `includeOperations` to filter which operations are generated and `ignoreTestCases` to exclude specific generated test cases. This example generates GET tests for `/users/{userId}` but skips authentication-related test cases.

```yaml
testGenerationSettings:
  includeOperations:
    "/users/{userId}": ["GET"]
  ignoreTestCases:
    "/users/{userId}":
      "GET":
        - "Invalid X-API-Key API key security"
        - "No security values provided"
```

--------------------------------

### Build Main CLI Package (JAR-based)

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/npm-publishing.md

Builds the fat JAR and prepares the npm package for the main CLI. Output is placed in `cli/build/npm/cli/`.

```bash
# Build fat JAR and prepare npm package
./npm/scripts/build-packages.sh

# Output: cli/build/npm/cli/
```

--------------------------------

### Run Development Tasks

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/example-value/README.md

Execute these Gradle commands to run tests and checks for the example-value module.

```bash
./gradlew :example-value:test
./gradlew :example-value:check
```

--------------------------------

### Filtering Test Cases by Rule Example

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/model.md

Configuration example for ignoring specific schema validation rules during test generation.

```APIDOC
## Filtering Test Cases by Rule

### Description
This section demonstrates how to configure settings to ignore test cases generated by specific rules.

### Configuration Example (YAML)
```yaml
testGenerationSettings:
  ignoreSchemaValidationRules:
    - art.galushko.openapi.testgen.rules.schema.OutOfMinimumLengthStringSchemaValidationRule
    - com.example.rules.SuffixValidationRule
```

### Note
These ignore settings primarily apply to schema and authentication rules. Test cases generated by providers can be filtered using `ignoreTestCases`.
```

--------------------------------

### Serve Documentation Locally with MkDocs

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/documentation-guide.md

Serve the documentation locally using the MkDocs command. This method does not regenerate Dokka output.

```bash
mkdocs serve
```

--------------------------------

### Apply convention plugins in module build.gradle.kts

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/CLAUDE.md

Demonstrates applying a library plugin with Allure reporting and configuring quality settings.

```kotlin
// Example: core/build.gradle.kts
plugins {
    id("testgen.library-with-allure")
}

testgenQuality {
    koverMinCoverage = 95
}

dependencies {
    api(libs.testgen.model)
    // ...
}
```

--------------------------------

### Configure via YAML File

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/npm/cli/README.md

Define generation settings in a YAML file and execute the CLI using that configuration.

```yaml
specFile: "openapi.yaml"
outputDir: "./generated"
generator: "template"
generatorOptions:
    templateSet: "restassured-java"
    templateVariables:
        package: "com.example.tests"
        baseUrl: "http://localhost:8080"
testGenerationSettings:
    maxTestCasesPerOperation: 500
    validSecurityValues:
        ApiKeyAuth: "test-key"
```

```bash
openapi-testgen --config-file config.yaml
```

--------------------------------

### Fallback for externalValue in OpenAPI specs

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/model.md

When using externalValue for examples in OpenAPI specifications, add an inline example as a fallback for test generation.

```yaml
responses:
  '200':
    content:
      application/json:
        examples:
          external:
            externalValue: 'https://example.com/response.json'
          inline:  # Fallback for test generation
            value:
              id: 1
              name: "example"
```

--------------------------------

### GET /users/{userId}

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/getting-started/end-to-end-workflow.md

Retrieves a specific user by their unique ID.

```APIDOC
## GET /users/{userId}

### Description
Retrieves a specific user by their unique ID.

### Method
GET

### Endpoint
/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier (UUID) of the user to retrieve.

### Response
#### Success Response (200)
- **User** (object) - The user object.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "Jane Smith"
}
```
```

--------------------------------

### Add Example-Value Dependency

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/example-value/README.md

Include this dependency in your build.gradle.kts file to use the module directly.

```kotlin
dependencies {
    implementation("art.galushko.openapi.testgen:example-value:<version>")
}
```

--------------------------------

### SchemaValueProvider Functional Interface

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/spi.md

The SchemaValueProvider is a functional interface used for providing schema-derived example values.

```APIDOC
## SchemaValueProvider

### Description
Schema-derived example values are generated via the `example-value` module. This functional interface provides schema-derived example values.

### Functional Signature
`fun provide(schema: Schema<*>, variationIndex: Int): Any?`

### Parameters
- `schema` (Schema<*>): The schema for which to provide an example value.
- `variationIndex` (Int): An index used to generate deterministic variations when uniqueness is required.

### Returns
- `Any?`: An example value derived from the schema, or `null` if not applicable.

### Guidelines
- Return `null` when not applicable.
- Keep outputs deterministic for identical inputs.
- Use `variationIndex` to generate deterministic variations when uniqueness is required.
```

--------------------------------

### Build Native Packages Locally

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/npm-publishing.md

Builds and tests the fat jar and native binary using GraalVM 21. Then prepares npm packages with the native binary. Requires GraalVM 21.

```bash
# Build and test fat jar and native binary (requires GraalVM 21)
./gradlew :cli:testDistributions

# Prepare npm packages with native binary
NATIVE_DIR="./cli/build/native/nativeCompile/openapi-testgen" FAT_JAR_DIR="./cli/build/libs" ./npm/scripts/build-packages.sh

# Output: cli/build/npm/cli-linux-x64/, cli/build/npm/cli-linux-arm64/, cli/build/npm/cli-darwin-arm64/, etc.
```

--------------------------------

### GET /users

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/getting-started/end-to-end-workflow.md

Retrieves a list of users. Supports pagination with 'page' and 'limit' query parameters.

```APIDOC
## GET /users

### Description
Retrieves a list of users. Supports pagination with 'page' and 'limit' query parameters.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **page** (integer) - Required - The page number to retrieve.
- **limit** (integer) - Optional - The maximum number of users to return per page. Must be between 1 and 100.

### Response
#### Success Response (200)
- **User** (array) - A list of user objects.

#### Response Example
```json
[
  {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "John Doe"
  }
]
```
```

--------------------------------

### Build Native Binary of OpenAPI Test Generator CLI

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/cli/README.md

Builds a native binary of the CLI from source using Gradle and GraalVM. This provides the fastest startup time.

```bash
./gradlew :cli:nativeCompile
./cli/build/native/nativeCompile/openapi-testgen --help
```

--------------------------------

### Run Pattern-Support Module Tests (Gradle)

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/pattern-support/README.md

Execute tests and checks for the pattern-support module using Gradle tasks.

```bash
./gradlew :pattern-support:test
./gradlew :pattern-support:check
```

--------------------------------

### Run GitHub release distributions

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/getting-started/installation.md

Commands to execute the CLI after downloading JVM or native distributions from GitHub.

```bash
unzip openapi-testgen-<version>.zip
./openapi-testgen-<version>/bin/openapi-testgen --help
```

```bash
java -jar openapi-testgen-<version>-all.jar --help
```

```bash
unzip openapi-testgen-<version>-linux-amd64.zip
cd openapi-testgen-<version>-linux-amd64
chmod +x openapi-testgen
./openapi-testgen --help
```

--------------------------------

### Default Provider Order Configuration

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/distribution-settings.md

Defines the default sequence of providers used for generating example values.

```yaml
providers:
    - enum
    - const
    - uuid
    - email
    - date
    - date-time
    - pattern      # Added by distribution (before plain-string)
    - plain-string
    - number
    - boolean
```

--------------------------------

### Build native image

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/cli/README.md

Compile the CLI into a native binary using GraalVM.

```bash
./gradlew :cli:nativeCompile
```

--------------------------------

### YAML Configuration File

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/configuration.md

A sample YAML configuration file defining generator settings, output paths, and security values.

```yaml
specFile: "openapi.yaml"
outputDir: "./build/generated"
generator: "test-suite-writer"
generatorOptions:
  outputFileName: "openapi-test-suites.json"
  writeMode: "MERGE"
testGenerationSettings:
  maxSchemaDepth: 50
  maxMergedSchemaDepth: 50
  maxSchemaCombinations: 100
  maxTestCasesPerOperation: 1000
  maxErrors: 100
  errorMode: "COLLECT_ALL"
  validSecurityValues:
    ApiKeyAuth: "test-key"
alwaysWriteTests: false
logLevel: "INFO"
```

--------------------------------

### Define required query parameter in OpenAPI

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/negative-testing.md

Example of an OpenAPI path definition where a query parameter is marked as required.

```yaml
paths:
    /persons:
        get:
            operationId: listPersons
            parameters:
                -   name: person
                    in: query
                    required: true
                    schema:
                        $ref: '#/components/schemas/Person'
```

--------------------------------

### Missed Required Parameter Test Output

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/catalogs/providers-catalog.md

Example JSON output generated by the MissedRequiredParameterTestProvider when a required parameter is omitted.

```json
{
  "name": "Missed Required Header Parameter X-Request-ID",
  "expectedStatusCode": 400,
  "rule": "art.galushko.openapi.testgen.providers.parameter.MissedRequiredParameterTestProvider"
}
```

--------------------------------

### Configure Maven Central and Gradle Plugin Portal Credentials via Environment Variables

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/publishing.md

Sets environment variables for Maven Central username and password, GPG signing key and passphrase, and Gradle Plugin Portal key and secret. Recommended for CI environments.

```bash
export ORG_GRADLE_PROJECT_mavenCentralUsername=your-portal-username
export ORG_GRADLE_PROJECT_mavenCentralPassword=your-portal-password
export ORG_GRADLE_PROJECT_signingInMemoryKey="$(cat private-key.asc)"
export ORG_GRADLE_PROJECT_signingInMemoryKeyPassword=your-gpg-passphrase
export GRADLE_PUBLISH_KEY=your-plugin-portal-key
export GRADLE_PUBLISH_SECRET=your-plugin-portal-secret
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/cli.md

The standard command structure for executing the openapi-testgen tool.

```bash
openapi-testgen [options]
```

--------------------------------

### Configure Basic Plugin Settings

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/plugin/README.md

Define the OpenAPI specification file and output directory for generated tests.

```kotlin
openApiTestGenerator {
    specFile.set("src/main/resources/openapi.yaml")
    outputDir.set(layout.buildDirectory.dir("generated/openapi-tests"))
    generator.set("template")
    generatorOptions.putAll(mapOf(
        "templateSet" to "restassured-java",
        "templateVariables" to mapOf(
            "package" to "com.example.generated",
            "baseUrl" to "http://localhost:8080",
        ),
    ))
}
```

--------------------------------

### Quick npm Package Publish

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/publishing.md

Builds and prepares npm packages, then publishes the main CLI package to the npm registry with public access. Navigate to the correct directory before running `npm publish`.

```bash
# Build and prepare packages
./npm/scripts/build-packages.sh

# Publish main package
cd cli/build/npm/cli && npm publish --access public
```

--------------------------------

### Format Violation for UUID

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/negative-testing.md

Example JSON output demonstrating a validation failure when a path parameter violates the UUID format.

```json
{
    "name": "Invalid Path userId parameter: Wrong UUID Format",
    "method": "DELETE",
    "path": "/users/{userId}",
    "pathParams": { "userId": "8e258b27-c787-49ef-9539-11461b251ffg" },
    "expectedStatusCode": 400,
    "rule": "art.galushko.openapi.testgen.rules.schema.WrongUuidFormatSchemaValidationRule"
}
```

--------------------------------

### Apply Convention Plugins in Gradle

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/development-setup.md

Apply convention plugins to standardize module builds. Customize settings like coverage thresholds as needed.

```kotlin
plugins {
    id("testgen.library-with-allure")
}

testgenQuality {
    koverMinCoverage = 95  // Customize coverage threshold
}
```

--------------------------------

### Run development and test tasks

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/cli/README.md

Execute unit, smoke, and distribution tests via Gradle.

```bash
# Unit tests
./gradlew :cli:test

# Smoke tests
./gradlew :cli:testFatJar
./gradlew :cli:testNative  # requires prior nativeCompile
./gradlew :cli:testDistributions
```

--------------------------------

### Define path parameter in OpenAPI spec

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/negative-testing.md

Example of an OpenAPI path definition with a regex pattern constraint for a path parameter.

```yaml
paths:
    /users/{userId}:
        get:
            operationId: getUser
            parameters:
                -   name: userId
                    in: path
                    required: true
                    schema:
                        type: string
                        pattern: '^[a-z0-9_]+$'
```

--------------------------------

### Run Distribution-Bundle Development Tasks

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/distribution-bundle/README.md

Execute standard Gradle tasks for testing and checking the distribution-bundle module.

```bash
./gradlew :distribution-bundle:test
./gradlew :distribution-bundle:check
```

--------------------------------

### Define Composed Schema with allOf

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/concepts/schema-composition.md

Example of a Pet schema using allOf to combine an Animal reference with additional properties.

```yaml
components:
    schemas:
        Pet:
            allOf:
                -   $ref: '#/components/schemas/Animal'
                -   type: object
                    properties:
                        name:
                            type: string
                            minLength: 1
                    required:
                        - name
        Animal:
            type: object
            properties:
                species:
                    type: string
            required:
                - species
```

--------------------------------

### Run all project checks

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/CLAUDE.md

Executes linting, tests, and API compatibility checks.

```bash
./gradlew check
```

--------------------------------

### Implementation Checklist

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/spi.md

Key considerations and requirements for implementing components within the test generation framework.

```APIDOC
## Implementation Checklist

### Core Requirements
- Deterministic iteration order; no non-deterministic maps/sets.
- No mutation of `TestGenerationContext` or `OpenAPI` models.
- Return empty sequences when a rule/provider is not applicable.
- Set `expectedStatusCode` explicitly for auth rules.
- Wrap provider logic with `runProviderSafely`.
```

--------------------------------

### Inspect Invalid Path Parameter Output

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/negative-testing.md

Example JSON output for a path parameter validation failure due to an invalid pattern.

```json
{
    "name": "Invalid Path userId parameter: Invalid Pattern",
    "method": "GET",
    "path": "/users/{userId}",
    "pathParams": { "userId": "AE." },
    "headers": [{ "key": "X-API-Key", "value": "test-api-key-123" }],
    "body": null,
    "expectedStatusCode": 400,
    "rule": "art.galushko.openapi.testgen.pattern.support.InvalidPatternSchemaValidationRule"
}
```

--------------------------------

### Generated test case for invalid query parameter value

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/negative-testing.md

Example of a test case generated when an object property violates schema constraints.

```json
{
    "name": "Invalid Query person parameter: Object Property age Invalid Type",
    "method": "GET",
    "path": "/persons",
    "queryParams": {
        "person": { "age": "abc", "name": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }
    },
    "expectedStatusCode": 400,
    "rule": "art.galushko.openapi.testgen.rules.composed.ObjectItemSchemaValidationRule"
}
```

--------------------------------

### Build JVM Distribution of OpenAPI Test Generator CLI

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/cli/README.md

Builds the JVM distribution of the CLI from source using Gradle. This generates an installable distribution.

```bash
./gradlew :cli:installDist
./cli/build/install/openapi-testgen/bin/openapi-testgen --help
```

--------------------------------

### Configure Composition Budget Settings

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/concepts/schema-composition.md

Settings to control recursion depth and schema combinations to prevent combinatorial explosion.

```yaml
testGenerationSettings:
    maxMergedSchemaDepth: 75      # Increase for deeply nested compositions
    maxSchemaCombinations: 200    # Increase for complex anyOf/oneOf
```

--------------------------------

### Run OpenAPI Test Generator CLI with npx

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/cli/README.md

Executes the CLI directly using npx without a global installation. Useful for quick checks or CI environments.

```bash
npx @openapi-testgen/cli --help
```

--------------------------------

### CLI Distribution Build Commands

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/development-setup.md

Build the command-line interface distribution. Includes tasks for creating the distribution archive, a shadow JAR, and a native executable.

```bash
./gradlew :cli:installDist
./gradlew :cli:shadowJar
./gradlew :cli:nativeCompile
```

--------------------------------

### SchemaValueProvider Functional Interface

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/reference/spi.md

Functional interface for providing schema-derived example values. It takes a schema and a variation index, returning a nullable Any? value. Outputs must be deterministic.

```kotlin
fun provide(schema: Schema<*>, variationIndex: Int): Any?
```

--------------------------------

### Include a Specific Method on All Paths Using Wildcard

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/configuration.md

Use a wildcard character (`*`) for the path to generate tests for a specific HTTP method (GET) across all API paths.

```yaml
testGenerationSettings:
  includeOperations:
    "*": ["GET"]
```

--------------------------------

### Publish Gradle Plugin

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/publishing.md

Use this command to publish the Gradle plugin to the Gradle Plugin Portal. Ensure you have the necessary permissions and configurations.

```bash
./gradlew :plugin:publishPlugins
```

--------------------------------

### Include Multiple Methods on a Single Path

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/configuration.md

Specify multiple HTTP methods (GET and DELETE) for a single API path (`/users/{userId}`) using the `includeOperations` configuration in YAML format.

```yaml
testGenerationSettings:
  includeOperations:
    "/users/{userId}": ["GET", "DELETE"]
```

--------------------------------

### Run Project Checks and Documentation Build

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/contributing/publishing.md

Executes Gradle tasks for checking code quality, API consistency, and building documentation. `docsBuild` includes Dokka generation.

```bash
./gradlew check
./gradlew apiCheck
./gradlew docsBuild
```

--------------------------------

### Example Budget Exceeded Error

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/concepts/error-handling.md

This JSON structure represents an error encountered when the schema combination limit is exceeded during request body validation. It provides details about the provider, the error message, and potential solutions.

```json
{
  "providerClass": "art.galushko.openapi.testgen.providers.body.RequestBodySchemaValidationTestProvider",
  "message": "Budget exceeded for POST /partial-success:\n  Generated: 5 schema combinations\n  Limit: 3\n\nPossible solutions:\n  1. Increase the limit by setting testGenerationSettings.maxSchemaCombinations to a higher value\n  2. Simplify the OpenAPI schema by reducing nested oneOf/anyOf/allOf structures\n  3. Use ignoreTestCases or ignoreSchemaValidationRules to exclude specific scenarios\n",
  "context": {
    "operation": {
      "path": "/partial-success",
      "method": "POST",
      "operationId": "partialSuccessOperation"
    }
  },
  "exceptionText": null
}
```

--------------------------------

### Configure CLI in package.json

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/npm/cli/README.md

Add a script to package.json to automate test generation.

```json
{
    "scripts": {
        "generate-tests": "openapi-testgen --spec-file api.yaml --output-dir tests --generator test-suite-writer --generator-option outputFileName=test-suites.json"
    }
}
```

--------------------------------

### Generated Test Suites Output

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/README.md

Example JSON output of generated test cases. This includes tests for invalid query parameters like 'page=0' (out of boundary) and 'page=1.5' (integer breaking), expecting a 400 status code.

```json
{
    "listUsers": {
        "path": "/users",
        "method": "GET",
        "operationName": "listUsers",
        "testCases": [
            {
                "name": "Invalid Query page parameter: Out Of Minimum Boundary Number",
                "method": "GET",
                "path": "/users",
                "queryParams": { "page": 0 },
                "headers": [{ "key": "X-API-Key", "value": "test-api-key-123" }],
                "expectedStatusCode": 400
            },
            {
                "name": "Invalid Query page parameter: Integer Breaking",
                "method": "GET",
                "path": "/users",
                "queryParams": { "page": 1.5 },
                "headers": [{ "key": "X-API-Key", "value": "test-api-key-123" }],
                "expectedStatusCode": 400
            }
        ]
    }
}
```

--------------------------------

### Filter Test Cases by Rule using jq

Source: https://github.com/galushkoart/openapi-testgen-monorepo/blob/main/docs/how-to/extending.md

Examples of using jq to filter generated JSON test suites by a specific rule's fully qualified class name (FQCN) or to count test cases per rule.

```bash
jq '.[] | .testCases[] | select(.rule == "com.example.rules.SuffixValidationRule")' \
  generated/test-suites.json
```

```bash
jq '[.[] | .testCases[].rule] | group_by(.) | map({rule: .[0], count: length})' \
  generated/test-suites.json
```