Add validate Mojo to Maven Plugin

[verhasi]

Description

This PR introduces a new validate Mojo to the openapi-generator-maven-plugin.

Historically, validating an OpenAPI specification within a Maven workflow required running the full generate goal, or relying on external plugins. As teams move toward centralized "API Contract" design modules (where specs are bundled without immediate code generation), there is a critical need to validate these descriptors independently and efficiently.

This new goal isolates the modern, rule-based OpenApiEvaluator logic (extracted from the CLI's validate command) and wraps it in a lightweight Maven lifecycle component.

The README of the openapi-generator-maven-plugin has been updated accordingly.

Key Changes

• New Mojo (ValidateMojo.java): Added the validate goal bound by default to the validate lifecycle phase.

• Modern Rule Evaluation: Leverages OpenApiEvaluator and RuleConfiguration to execute deep structural and semantic spec validation.

• Fail-Fast Engine: Configured to fail the build immediately with actionable error logs if the spec violates OpenAPI specifications, while remaining silent and non-blocking on soft recommendations.

• m2e Integration: Updated lifecycle-mapping-metadata.xml to ensure Eclipse/m2e environments can seamlessly run incremental validation on workspace file changes.

Configuration & Usage

Single File Validation (Standard)

For validating a single targeted OpenAPI specification file:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${project.version}</version>
    <executions>
        <execution>
            <phase>validate</phase>
            <goals>
                <goal>validate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/api/openapi.yaml</inputSpec>
            </configuration>
        </execution>
    </executions>
</plugin>

Bulk Validation & Directory Aggregation (Future-Proofing)

• Replaced the single-file limitation with an asset-aggregation strategy.
• Added a directory scanner (inputSpecRootDirectory) that automatically aggregates and iterates through all discovered OpenAPI specification documents within a target folder, perfectly mirroring how the existing generate goal handles directory inputs.
• Provided native support for multi-file array inputs via Maven XML configuration blocks and comma-separated CLI string overrides. This acts as a powerful enhancement over how the generate goal currently handles inputSpec.
• This ensures the validate goal can natively scale to support modular, split-spec environments and multi-API repositories without requiring separate execution blocks for every file. Crucially, this allows users to capture all validation issues across their entire spec ecosystem in a single pass, completely eliminating the need to fix errors one-by-one through repeated, slow Maven iterations.

Technical Benefits

• Fail-Fast CI/CD: Shifts API validation to the very beginning of the build sequence. Broken specs halt the pipeline in seconds rather than waiting minutes for downstream code generation or compilation failures.

• Resource Optimization: No unnecessary I/O file writing or code generation steps are performed when a user only wants to sanity-check a contract change.

Verification Results

• Tested locally against a suite of valid OpenAPI 3.0.x/3.1.x schemas (Build passes successfully).

• Tested against intentionally malformed/invalid specs (Build accurately throws MojoFailureException and outputs specific syntax/structural errors cleanly to the console logs).

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• If your PR solves a reported issue, reference it using GitHub's linking syntax (e.g., having "fixes #123" present in the PR description)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

---

Summary by cubic

Adds a new validate goal to the openapi-generator-maven-plugin to validate OpenAPI specs early in the Maven lifecycle without generating code. It uses the rule-based engine, fails the build on errors, and now correctly handles skip checks and m2e integration.

• New Features

  • New ValidateMojo bound to validate; runs OpenApiEvaluator with RuleConfiguration (fail-fast on errors; recommendations are non-blocking).
  • Multiple inputs supported: single inputSpec, XML list, comma-separated CLI override, and inputSpecRootDirectory scan.
  • m2e lifecycle mapping for incremental validation in Eclipse.
  • README updated; unit and integration tests for single, multi-file, directory, CLI override, and failure cases.

• Bug Fixes

  • Added missing validate goal to m2e lifecycle mapping.
  • Reordered ValidateMojo execution so skip flags are checked before input validation.

^{Written for commit 5629dd3. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 26 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>