Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
## Release Notes

`1.0.5`

- Added `GeneratorException` class for generation related errors.
- Upgraded `apiphany` to `1.0.20`.
- Upgraded `swagger-jaxrs2-jakarta` to `2.2.41`.
- Upgraded `maven-plugin-api` to `3.9.11`.

---

`1.0.4`

- Upgraded `apiphany` to `1.0.18`.
Expand Down
15 changes: 14 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,24 +15,27 @@ A Maven plugin for generating OpenAPI documentation offline.
![Build (develop)](https://github.com/raduking/openapi-offline-generator-plugin/actions/workflows/build.yml/badge.svg?branch=develop)

## Features

- 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)

## Prerequisites

- Java 25+
- Maven 3.8+

## Quick Start

Add the plugin to your project POM:
```xml
<build>
<plugins>
<plugin>
<groupId>com.example</groupId>
<artifactId>openapi-offline-generator-plugin</artifactId>
<version>1.0.4</version>
<version>1.0.5</version>
<executions>
<execution>
<id>generate-openapi-offline</id>
Expand All @@ -59,6 +62,7 @@ mvn clean verify
Artifacts will be placed under target/openapi.

## Configuration Options

| Field | Description | Default |
|-------|-------------|----------------------------------------------------|
| `packagesToScan` | The base package(s) to scan for REST controllers (multiple packages can be comma-separated) |
Expand Down Expand Up @@ -135,17 +139,20 @@ Attach generated spec:
```

## Offline Philosophy

- All enrichment (bundling, ordering, validation) happens at build time
- Encourages contract-first development
- Makes specs diff-friendly for code review

## Roadmap

- Gradle plugin wrapper
- Multi-module aggregation
- OpenAPI 4.x (when finalized)
- Pluggable preprocessors

## Contributing

1. Fork
2. Create feature branch
3. Add tests (mvn test)
Expand All @@ -160,18 +167,24 @@ mvn clean install
```

## Release (Maintainers)

- Update [CHANGELOG](CHANGELOG.md)
- Update [README](README.md)
- Set release version
- mvn clean deploy -Prelease

## License

[Apache License 2.0](LICENSE)

## Security

Report vulnerabilities via private issue or security email channel. Do not open public issues until disclosure window ends.

## Acknowledgements

Inspired by needs for deterministic, auditable API specification generation in regulated environments.

## Contact

Open an issue for bugs, discussions for ideas.
43 changes: 30 additions & 13 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

<groupId>io.github.raduking</groupId>
<artifactId>openapi-offline-generator-plugin</artifactId>
<version>1.0.4</version>
<version>1.0.5</version>
<packaging>maven-plugin</packaging>

<name>${project.groupId}:${project.artifactId}</name>
Expand Down Expand Up @@ -51,13 +51,25 @@
<maven.compiler.target>${java.version}</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

<maven.compiler.plugin.version>3.14.1</maven.compiler.plugin.version>
<maven.plugin.plugin.version>3.15.2</maven.plugin.plugin.version>
<!-- Other dependencies versions -->
<maven.plugin.api.version>3.9.11</maven.plugin.api.version>
<maven.core.version>3.9.11</maven.core.version>

<swagger.jaxrs2.jakarta.version>2.2.41</swagger.jaxrs2.jakarta.version>
<springdoc.openapi.starter.webmvc.api.version>2.8.13</springdoc.openapi.starter.webmvc.api.version>
<apiphany.version>1.0.20</apiphany.version>
<therapi.runtime.javadoc.version>0.15.0</therapi.runtime.javadoc.version>

<!-- Publishing dependencies versions -->
<maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
<central.publishing.maven.plugin.version>0.9.0</central.publishing.maven.plugin.version>

<!-- Other plugin versions -->
<maven.plugin.plugin.version>3.15.2</maven.plugin.plugin.version>
<spotless.maven.plugin.version>2.46.1</spotless.maven.plugin.version>
<org.eclipse.jdt.core.version>3.42.0</org.eclipse.jdt.core.version>
<eclipse.formatter.version>4.36</eclipse.formatter.version>

<!-- Jacoco arguments empty by default -->
<jacocoArgLine></jacocoArgLine>

Expand All @@ -70,6 +82,7 @@

<!-- Testing command line options -->
<oogpArgLine>
-XX:+EnableDynamicAgentLoading
--add-opens java.base/java.lang.reflect=ALL-UNNAMED
--add-opens java.base/sun.reflect.annotation=ALL-UNNAMED
</oogpArgLine>
Expand All @@ -87,13 +100,13 @@
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2-jakarta</artifactId>
<version>2.2.39</version>
<version>${swagger.jaxrs2.jakarta.version}</version>
</dependency>

<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.8.13</version>
<version>${springdoc.openapi.starter.webmvc.api.version}</version>
</dependency>

<!-- Jakarta -->
Expand All @@ -117,14 +130,14 @@
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-plugin-api</artifactId>
<version>3.9.6</version>
<version>${maven.plugin.api.version}</version>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-core</artifactId>
<version>3.9.11</version>
<version>${maven.core.version}</version>
<scope>provided</scope>
</dependency>

Expand All @@ -138,14 +151,14 @@
<dependency>
<groupId>io.github.raduking</groupId>
<artifactId>apiphany</artifactId>
<version>1.0.18</version>
<version>${apiphany.version}</version>
</dependency>

<!-- Javadoc -->
<dependency>
<groupId>com.github.therapi</groupId>
<artifactId>therapi-runtime-javadoc</artifactId>
<version>0.15.0</version>
<version>${therapi.runtime.javadoc.version}</version>
</dependency>

<!-- Testing -->
Expand Down Expand Up @@ -191,6 +204,11 @@
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

<build>
Expand Down Expand Up @@ -244,7 +262,6 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven.compiler.plugin.version}</version>
<configuration>
<source>${maven.compiler.source}</source>
<target>${maven.compiler.target}</target>
Expand Down Expand Up @@ -345,19 +362,19 @@
<plugin>
<groupId>com.diffplug.spotless</groupId>
<artifactId>spotless-maven-plugin</artifactId>
<version>2.46.1</version>
<version>${spotless.maven.plugin.version}</version>
<dependencies>
<dependency>
<groupId>org.eclipse.jdt</groupId>
<artifactId>org.eclipse.jdt.core</artifactId>
<version>3.42.0</version>
<version>${org.eclipse.jdt.core.version}</version>
</dependency>
</dependencies>
<configuration>
<java>
<eclipse>
<file>${project.basedir}/formatter/java-formatter.xml</file>
<version>4.36</version>
<version>${eclipse.formatter.version}</version>
</eclipse>
<removeUnusedImports/>
<trimTrailingWhitespace/>
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/org/oogp/Errors.java
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ public class Errors {
/**
* The logger.
*/
private static final Logger LOGGER = LoggerFactory.getLogger(Conversions.class);
private static final Logger LOGGER = LoggerFactory.getLogger(Errors.class);

/**
* Hide constructor.
Expand Down
34 changes: 34 additions & 0 deletions src/main/java/org/oogp/GeneratorException.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
package org.oogp;

/**
* Exception class for generator-related errors.
*
* @author Radu Sebastian LAZIN
*/
public class GeneratorException extends RuntimeException {

/**
* Serial version UID.
*/
private static final long serialVersionUID = -4336559629781875288L;

/**
* Constructs a new {@link GeneratorException} with the specified detail message.
*
* @param message the detail message
*/
public GeneratorException(final String message) {
super(message);
}

/**
* Constructs a new {@link GeneratorException} with the specified detail message and cause.
*
* @param message the detail message
* @param cause the cause of the exception
*/
public GeneratorException(final String message, final Throwable cause) {
super(message, cause);
}

}
27 changes: 16 additions & 11 deletions src/main/java/org/oogp/OpenApiGenerator.java
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
package org.oogp;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

import org.apiphany.json.JsonBuilder;
import org.morphix.reflection.Constructors;
import org.oogp.jakarta.OpenApiSpecJakartaGenerator;
import org.oogp.spring.OpenApiSpecSpringDocGenerator;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

/**
* Main class for OpenAPI generation used in the CLI mode.
*
Expand All @@ -22,18 +22,23 @@ public class OpenApiGenerator {
* @param args the command line arguments
* @throws Exception in case of errors
*/
static void main(final String[] args) throws Exception {
static void main(final String[] args) {
if (args.length != 1) {
System.err.println("Expected path to properties JSON");
System.exit(2);
}
try {
Path propertiesPath = Path.of(args[0]);
String json = Files.readString(propertiesPath);

Path propertiesPath = Path.of(args[0]);
String json = Files.readString(propertiesPath);
GeneratorProperties properties = JsonBuilder.fromJson(json, GeneratorProperties.class);
properties.applyDefaults(null, null);
GeneratorProperties properties = JsonBuilder.fromJson(json, GeneratorProperties.class);
properties.applyDefaults(null, null);

generate(properties);
generate(properties);
} catch (Exception e) {
e.printStackTrace();
System.exit(3);
}
}

/**
Expand All @@ -46,7 +51,7 @@ public static void generate(final GeneratorProperties properties) throws IOExcep
switch (ProjectType.fromString(properties.getProjectType())) {
case JAKARTA -> OpenApiSpecJakartaGenerator.generate(properties);
case SPRING -> OpenApiSpecSpringDocGenerator.generate(properties);
default -> throw new RuntimeException("Unknown project type: " + properties.getProjectType());
default -> throw new GeneratorException("Unknown project type: " + properties.getProjectType());
}
}

Expand Down
Loading
Loading