[BUG] : Annotation scanning runs with baseClass = null, causing full classpath scan

[Ishita-190]

Describe the bug.

In the Ktor integration, annotation discovery may trigger a full classpath scan when AsyncApiConfiguration.baseClass is not configured.

Because a null package is passed to the default annotation scanner, ClassGraph runs without any package restriction and scans everything visible to the classloader. Since baseClass appears optional, this behavior is not obvious from configuration.

Root cause

DefaultAnnotationScanner restricts scanning only when a package is provided:

if (scanPackage != null) {
    acceptPackages(scanPackage)
}

When scanPackage == null, no filter is applied and the entire classpath is scanned.

In the Ktor module:

applicationPackage = baseClass?.java?.package

If baseClass is not set:

• applicationPackage becomes null
• scanPackage becomes null
• a full classpath scan occurs during AsyncAPI initialization.

This can significantly degrade startup performance and resource usage by unintentionally triggering worst-case full-classpath scanning when baseClass is not set.

Proposed solution

Enable annotation scanning in Ktor only when an explicit base package is provided.

Suggested behavior:

• If scanAnnotations == false → do not create AnnotationProvider.

• If scanAnnotations == true but baseClass == null:

  • skip creating AnnotationProvider and asyncApiAnnotationExtension

  • log a warning such as:

    “AsyncAPI annotation scanning is disabled because baseClass is not set.”

• Only when scanAnnotations == true and baseClass != null:

  • use baseClass.java.package as the scan root.

This makes annotation scanning an explicit opt-in, prevents accidental full-classpath scans, and aligns behavior with the Spring integration where scanning is always anchored to a known package.

Expected behavior

When baseClass is not configured, annotation scanning should not run, or should remain scoped to a safe default. The application should start without performing a full classpath scan unless a base package is explicitly provided.

Annotation scanning should only occur when a clear package boundary is defined by the user.

Screenshots

kotlin-asyncapi-ktor/src/main/kotlin/com/asyncapi/kotlinasyncapi/ktor/AsyncApiModule.kt

kotlin-asyncapi-context/src/main/kotlin/com/asyncapi/kotlinasyncapi/context/annotation/AnnotationScanner.kt

How to Reproduce

1. Create a Ktor application using the AsyncAPI Ktor plugin.
2. Enable annotation scanning.
3. Do not configure baseClass.
4. Start the application.
5. Observe that annotation scanning still runs and scans the entire classpath.

🖥️ Device Information [optional]

OS: Windows 11 (x64)
JDK: OpenJDK 17.0.9
Build Tool: Maven 3.9.6
Kotlin Version: 1.9.x

👀 Have you checked for similar open issues?

• I checked and didn't find similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue ?

Yes I am willing to submit a PR!

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[lorenzsimon]

Hi @Ishita-190, thanks for the report. The project follows a zero-config first approach. This lets users start simple and optimise when needed. But there is actually another bug in the ktor module initialisation. The AnnotationProvider is meant to be lazily initialised. Meaning the class path scanning should happen on the first request and not on application startup. That should be easy to fix.

[Ishita-190]

@lorenzsimon Thank you for the clarification! I'll start working on the bug.