ApiHug API Design Copilot FAQ

Trivial

IDEA plugin

Plugin Release

Proto module compile issue

JVM version compatibility is critical for successful proto module compilation.

Two JVM versions are involved:

The toolchain version defined in the project’s gradle/java.gradle file.
The JVM version of the build environment (used by Gradle at runtime).

A version mismatch between these can cause the protobuf wire compiler to fail silently.

To prevent issues:

Ensure the proto module’s target compilation version is <= build environment JVM version.

Java version:

Project	Compile(gradle)	Proto Module
21	21	Default or `<=21`
21	17	`<=17`
17	21	Default or `<=21`

Project toolchain Java version {project-root}/gradle/java.gradle:

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Gradle JVM version, which will be printed when starting compilation:

Java version: 19.0.1
Gradle version: 8.14.3
Current dir: /user/home/project/myproject
Spring Boot version: 3.5.5
Spring Dependency version: 1.1.7
Spring Ai version: 1.0.0
Spring Cloud version: 2024.0.1
ApiHug version: 1.4.3-M8
All Modules: [project ':sample-proto',':sample-app']

Each module can override the Java version in its own build.gradle.

ProtoBuf

Proto file cannot be recognized

Currently, there are two popular Proto buffer plugins supported by IDEs:

Built-in IDE plugin, provided by JetBrains s.r.o. ✅✅✅
Third-party HIGAN plugin ❌❌❌

These two plugins conflict with each other and only one can be enabled at a time. ⚠️

The ApiHug Plugin relies on the IDE’s built-in Proto Editor plugin for AST parsing, so the JetBrains s.r.o. ✅ Proto plugin must be enabled:

Proto file import fails, cannot recognize the proto import

ApiHug SDK proto import import "swagger/annotations.proto"; fails with an error:

ApiHug SDK proto import import "swagger/annotations.proto"; fails:

01: Compile the project (via markdown or gradle task)

02: After successful compilation, check the build cache of the proto project:

{PROJECT}/{PROTO-MODULE}/build/extracted-include-protos:

03: If the import still fails, manually configure the proto import path; if imports are still not recognized, please add the path manually:

Open the Settings panel
Locate Protocol Buffers
Un-check Configure Automatically
Add {PROJECT}/{PROTO-MODULE}/build/extracted-include-protos to the Import Paths:

Since Plugin version 0.7.6, these predefined protos are included by the plugin.

Eventually, all import statements should turn green!

⚠️ Occasionally, the official proto editor may crash; please pay attention to any crash notifications.

If the issue persists even after restarting IDEA, please report it to us: report issue

Gradle

Cannot recognize as Gradle project

The IDE should display a Load Gradle Project notification. If notifications are disabled, open the Notification panel to trigger it manually.

IDE should pop up a notification: Load Gradle Project; if the notification was disabled, please open the Notification panel to load it manually!