DEV Community

Istvan Verhas
Istvan Verhas

Posted on

OpenAPI Spec Validation in Maven Is Now a First-Class Citizen (v7.24.0)

#java #api #mvn #openapi

OpenAPI Generator v7.24.0 shipped with 170+ enhancements, but one addition quietly fills a gap that's been annoying Java teams for years: a dedicated validate goal for the Maven plugin.

Until now, validating an OpenAPI specification in a Maven workflow meant either running the full generate goal (slow, unnecessary I/O) or pulling in external plugins. If your team maintains an "API Contract" module — where specs live without immediate code generation — you had no lightweight way to verify those contracts as part of the build.

That changes now.

The Problem

Consider a typical API-first project structure:

my-service/
├── api-contract/          ← OpenAPI specs live here (no code generation)
│   └── src/main/resources/
│       └── openapi.yaml
├── service-impl/          ← Generated code + business logic
└── service-client/        ← Generated client SDK
Enter fullscreen mode Exit fullscreen mode

The api-contract module exists purely to version and validate specs. But without a validate goal, your CI pipeline couldn't catch spec errors until the downstream generate step — minutes later, buried in code generation failures.

The Solution: validate Goal 

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.24.0</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>
Enter fullscreen mode Exit fullscreen mode

That's it. Your spec is validated at the very beginning of the Maven lifecycle — before compile, before generate, before anything else.

Why This Matters

1. Fail-Fast CI/CD

Broken specs halt the pipeline in seconds rather than waiting minutes for downstream code generation and compilation failures. The validation runs the same rule-based engine (OpenApiEvaluator) that powers the CLI validate command — deep structural and semantic checks, not just YAML syntax.

2. No Unnecessary Work

The validate goal performs zero I/O beyond reading the spec. No file generation, no template processing, no output directories. Pure validation.

3. Bulk Validation

Got a multi-API repository? Use inputSpecRootDirectory to validate all specs in one pass:

<configuration>
    <inputSpecRootDirectory>${project.basedir}/src/main/resources/apis/</inputSpecRootDirectory>
</configuration>
Enter fullscreen mode Exit fullscreen mode

No more separate execution blocks per file. All validation issues across your entire spec ecosystem in a single Maven invocation.

4. Eclipse/m2e Integration

The goal includes proper lifecycle-mapping-metadata.xml configuration, so Eclipse users get incremental validation on workspace file changes. Edit your spec, save, see errors immediately.

Behavior

  • Errors (structural/semantic violations): Fail the build with actionable messages
  • Recommendations (best practice suggestions): Logged but non-blocking
  • Skip support: Honors the same skip flags as the generate goal

The Bigger Picture: Contract-First Development

This feature enables a cleaner separation in contract-first (API-first) development:

mvn validate    ← Spec is correct (new goal!)
mvn generate    ← Code is generated from spec
mvn compile     ← Generated + hand-written code compiles
mvn test        ← Everything works together
Enter fullscreen mode Exit fullscreen mode

Each phase does one thing. The validate goal ensures you never waste time generating code from a broken spec.

Try It

Upgrade to openapi-generator-maven-plugin 7.24.0 and add the execution block above. If you maintain API contract modules that don't generate code, this is the missing piece for your build pipeline.

Links

Full disclosure: I authored this contribution (PR #23911). The implementation leverages the existing OpenApiEvaluator rule engine from the CLI and wraps it as a Maven lifecycle component.

Top comments (0)