Milestone 2.0.0-RELEASE

2.0.0-RELEASE is a major milestone for ApiHug, introducing numerous breaking changes to pave the way for a next-generation, LLM-friendly API specification and tooling ecosystem.

😆 Guide：

ApiHug - API design Copilot

SDK [2.0.0-RELEASE] - 2025-12-10

Migrated JavaPoet from Square to Palantir fork
Replaced Google’s protobuf parser with Square’s Wire engine
Laid groundwork for Protobuf Schema Catalog support

Plugin [1.0.0] - 2025-12-10

Upgraded to SDK 2.0.0-RELEASE
Removed legacy Protocol Buffer plugin dependencies
Adopted a lightweight, pure Wire-based protobuf compiler
Removed AI-related components for a leaner, more focused design
Cached metadata in human-readable text format—LLM-friendly
Various bug fixes

⚠️⚠️⚠️ Do NOT upgrade to Spring Boot 4.0+ (as of December 2025) — the SDK is not yet compatible due to breaking changes introduced in Spring Boot 4.0. ⚠️⚠️⚠️

Attempting to do so may result in severe and difficult-to-diagnose build or runtime errors.

For details on the extensive breaking changes, please refer to the official:

Spring Boot 4.0 Migration Guide

New Feature

Polymorphism support via Protocol Buffers’ oneof construct.
Compact OpenAPI output by leveraging OAS allOf to unwrap and simplify response wrappers.
Ultra-fast, lightweight compiler for rapid generation and iteration.
Rich metadata export to enable advanced tooling and integrations.
LLM-ready specifications — laying the foundation for specification-driven development (TBD).

Upgrade steps

Refer apihug-demo/libs.versions.toml

Upgrade ApiHug SDK: {PROJECT_ROOT}/gradle/libs.versions.toml find apihug = "1.0.0-RELEASE" please upgrade to 2.0.0-RELEASE+
Upgrade ApiHug IDEA plugin to 1.0.0+ ApiHug - API design Copilot
Make sure spring boot is <4.0, better 3.8~ as the spring boot 4.0 has break change!!
Update your command line, now the lite compile will automatically run before build, so no need to specify wire or stub command
structure change:

Wire

Generated vs hand-written directories

Generated directories (_*_): any directory whose name is wrapped with leading and trailing underscores (for example _api_) is created by the apihug tools and is read-only.
Do not edit files in these directories by hand.
They are regenerated by tooling and may be overwritten at any time.
Hand-written directories: plain-named directories such as java and proto are intended for developer-authored source code and schemas.
Java application code and tests should live under java.
Protocol Buffer definitions (.proto files) should live under proto.

Production sources (`src/main`)

The production source layout is:

src/main/
  java/        → Core application logic (hand-written Java code)
  _api_/       → Java classes generated from Wire/contract definitions (production code, read-only)
  proto/       → `.proto` schema files (treated as resources for code generation)

Gradle is configured so that:

src/main/_api_ is added to sourceSets.main.java.srcDirs and compiled as part of the main Java sources.
src/main/proto is added to sourceSets.main.resources.srcDir and included as resources, allowing code generators or tools to read the .proto files at build time.

Test sources (`src/test`)

The test layout extends the same conventions to test code:

src/test/
  java/        → Standard unit & integration tests (JUnit, etc.)
  _api_/       → API guardian/contract tests compiled and run as part of the `test` task

Gradle is configured so that src/test/_api_ is added to sourceSets.test.java.srcDirs, meaning these tests are compiled and executed together with the standard test sources.

Kola contract tests (`src/test-kola`)

Kola tests use a dedicated source set and task to model contract-style, end-to-end tests.

src/
  main/
    java/          // Production Java source code
    resources/     // Production resources
  test/
    java/          // Standard unit/integration tests (JUnit, etc.)
    resources/     // Resources for standard tests
  test-kola/
    java/          // Auto-generated Java test classes (compiled and executed)
    groovy/        // Groovy DSL files (treated as resources; NOT compiled)
    resources/     // Additional test resources (contracts, fixtures, configs)

The Gradle configuration defines a testKola source set:

src/test-kola/java is used for generated Java test classes.
src/test-kola/resources and src/test-kola/groovy are both registered as resource directories.
Groovy DSL files in groovy are not compiled; they are read by generators or test tooling at build time.
The testKola classpath includes outputs from both main and test source sets, so helper utilities and base test classes can be reused.

A dedicated testKola Gradle task runs only the Kola-generated tests using JUnit Platform, while the standard test task also uses JUnit Platform for consistency.

Practical guidelines

Never modify generated _api_ sources by hand; instead, change proto/contracts and re-run generation.
Keep business logic in src/main/java and tests in src/test/java.
Place contract definitions and schemas in src/main/proto, and Kola DSL scripts in src/test-kola/groovy.
Use test for regular unit/integration tests and testKola for contract-style, end-to-end verification.

Stub

Generated vs hand-written directories

Generated directories (_*_): any directory whose name is wrapped with leading and trailing underscores (for example _api_, _mcp_, _domain_, _cloud_) is created by the apihug tools and is read-only.
Do not edit files in these directories by hand.
They are regenerated by tooling and may be overwritten at any time.
Hand-written directories: plain-named directories such as java and trait are intended for developer-authored source code.
Business logic, services, controllers, and custom traits should live here.

Production sources (`src/main`)

The production source layout is intentionally split across several directories:

src/main/
  java/        → Hand-written business logic, services, controllers, etc.
  _api_/       → Generated DTOs and REST interfaces (apihug-generated, read-only)
  trait/       → Shared mixin/trait classes that can be customized by developers
  _mcp_/       → Generated microservice contract or protocol code (read-only)
  _domain_/    → Generated core domain models, aggregates, value objects (read-only)
  _cloud_/     → Generated cloud/integration stubs, endpoints, or adapters (read-only)

Although the sources are physically split across multiple directories, they all belong to the same production module. Gradle is configured to add these directories to sourceSets.main.java.srcDirs, so all of them are compiled together into a single JAR.

Test sources (`src/test`)

The test layout mirrors the production structure to keep tests close to the code they validate:

src/test/
  java/        → Unit and integration tests for core logic
  _api_/       → Contract/guardian tests for the API layer (often using generated DTOs)
  trait/       → Tests for trait/mixin behavior
  _mcp_/       → Validation tests for protocol contracts
  _domain_/    → Domain model invariant and behavior tests
  _cloud_/     → Cloud/integration contract tests and generated stubs

All of these directories are registered in sourceSets.test.java.srcDirs, so the tests are compiled and executed as part of the standard Gradle test task and share the same classpath (main + test outputs and test dependencies).

Practical guidelines

Never modify generated directories (_api_, _mcp_, _domain_, _cloud_). Instead, change the underlying contract or generation inputs and re-run the generator.
Place custom logic in java and trait so that changes are stable across code generation runs.
Create tests in the matching directory under src/test to keep production and test code aligned in structure.

Proto

// old
import "extend/version.proto";
import "swagger/annotations.proto";
import "extend/domain.proto";

// new 
import "apihug/protobuf/extend/version.proto";
import "apihug/protobuf/swagger/annotations.proto";
import "apihug/protobuf/extend/domain.proto";

Syntax

Polymorphism support via oneof — OAS
Stream definition support === gRPC (server-side not yet implemented): definition, implementation…
Support for upload and downloader definitions (server-side not yet implemented)
Optimization for single-response definitions (non-reference types)
Definition of complex types
Schema definition
Support for internal/external/hide API markers

Gradle

wire projects support the protoImport syntax to import third-party proto dependencies
stub projects support the wireImport syntax to import wire module dependencies; using implementation causes no syntax error but results in empty compilation for the stub command

On this page