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

Module Structure

src/
├── main/
│   ├── java/        → Hand-written core application logic  
│   ├── api/         → Generated Java classes (via Wire compiler, production-ready)  
│   └── proto/       → `.proto` definition files (included as resources; not compiled here)  
│
├── test/
│   ├── java/        → Standard unit and integration tests  
│   └── api/         → API contract/guardian tests (compiled and run during `test`)  
│
└── test-kola/
    ├── java/        → Auto-generated Java test classes (compiled & executed via JUnit Platform)  
    ├── groovy/      → Human-authored Groovy DSL scripts (treated as resources, **not compiled**)  
    └── resources/   → Additional test assets (e.g., contracts, fixtures, configs)

Notes

The test-kola/groovy directory contains handwritten Groovy DSL scripts that define test contracts or behaviors. These are not compiled by Gradle.
During the build, these Groovy scripts are copied as resources into the testKola source set output, where a custom code generator reads them to produce Java test classes.
The generated Java tests in test-kola/java are compiled and executed as part of the testKola Gradle task using the JUnit Platform.

Stub

Production Source Layout

The application’s production code is intentionally split across multiple
directories under src/main/ for clarity and maintainability:

src/main/
  ├── java/      → Hand-written business logic, services, controllers, etc.
  ├── api/       → Generated DTOs, REST interfaces
  ├── trait/     → Generated or shared mixin/trait classes
  ├── mcp/       → Generated microservice contract or protocol code
  └── domain/    → Core domain models, aggregates, value objects

Despite this physical separation, all these sources belong to the same
production module and must be compiled together into a single JAR.

Test Source Layout

Mirror the same logical structure in test code for organizational symmetry:

src/test/
  ├── java/      → Unit/integration tests for core logic
  ├── api/       → Contract/guardian tests for API layer
  ├── trait/     → Tests for trait/mixin behavior
  ├── mcp/       → Validation tests for protocol contracts
  └── domain/    → Domain model invariant and behavior tests

All test sources are part of the standard test source set and run together
via the test task. They share the same classpath (main + test output) and
dependencies (JUnit, Mockito, etc.).

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