A Maven plugin for generating OpenAPI documentation offline.
- Pure offline generation (no network calls, no Spring context loading for Spring applications)
- Fast, reproducible, CI friendly
- Supports YAML, JSON bundle outputs
- Deterministic builds (stable ordering / hashing)
- Java 25+
- Maven 3.8+
Add the plugin to your project POM:
<build>
<plugins>
<plugin>
<groupId>com.example</groupId>
<artifactId>openapi-offline-generator-plugin</artifactId>
<version>1.0.5</version>
<executions>
<execution>
<id>generate-openapi-offline</id>
<phase>process-classes</phase>
<goals>
<goal>generate-openapi</goal>
</goals>
</execution>
</executions>
<configuration>
<properties>
<!-- plugin properties -->
</properties>
</configuration>
</plugin>
</plugins>
</build>Run:
mvn clean verify
Artifacts will be placed under target/openapi.
| Field | Description | Default |
|---|---|---|
packagesToScan |
The base package(s) to scan for REST controllers (multiple packages can be comma-separated) | |
outputFile |
The output file for the generated OpenAPI definition | ${project.build.directory}/generated-openapi.yaml |
classesDir |
The compiled classes directory (where Spring controllers are located) | ${project.build.outputDirectory} |
schemaForObjectClass |
The schema to use when the schema implementation is Object.class |
object |
projectType |
The project type (spring/jakarta) |
spring |
oauth2 |
OAuth2 options (see below) | |
extensions |
OpenAPI extensions (as map) |
| Field | Description | Default |
|---|---|---|
enabled |
Flag to enable/disable OAuth2 | false |
authorizationUrl |
The authorization URL | http://automatically/replaced/on/runtime |
Minimal config:
<configuration>
<properties>
<outputFile>${project.basedir}/spec/openapi.yaml</outputFile>
</properties>
</configuration>OpenAPI extensions:
<configuration>
<properties>
<extensions>
<x-internal-hostname>http://my-internal-host:8080</x-internal-hostname>
</extensions>
</properties>
</configuration>Typical phases:
- prepare-resources: (optional preprocessing)
- compile: (class compilation)
- process-classes: plugin execution
- package: include generated spec as artifact classifier if desired
Attach generated spec:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>attach-openapi</id>
<phase>package</phase>
<goals>
<goal>resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/generated-spec</outputDirectory>
<resources>
<resource>
<directory>${project.basedir}/spec</directory>
<includes>
<include>generated-openapi.yaml</include>
</includes>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>- All enrichment (bundling, ordering, validation) happens at build time
- Encourages contract-first development
- Makes specs diff-friendly for code review
- Gradle plugin wrapper
- Multi-module aggregation
- OpenAPI 4.x (when finalized)
- Pluggable preprocessors
- Fork
- Create feature branch
- Add tests (mvn test)
- Run full build (mvn verify)
- Open PR referencing any related issue
Snapshot install:
mvn clean install
Report vulnerabilities via private issue or security email channel. Do not open public issues until disclosure window ends.
Inspired by needs for deterministic, auditable API specification generation in regulated environments.
Open an issue for bugs, discussions for ideas.