使用Javalin OpenAPI注解时遭遇“no api definition provided”错误

开发Javalin项目时，尝试通过OpenAPI注解自动生成REST API文档，已在控制器方法上添加@OpenApi注解，但访问Swagger UI或ReDoc时，始终显示“no api definition provided”错误。

项目代码与配置 #

Kotlin核心代码 #

package org.example

import io.javalin.Javalin
import io.javalin.apibuilder.ApiBuilder.*
import io.javalin.http.Context
import io.javalin.openapi.*
import io.javalin.openapi.plugin.OpenApiPlugin
import io.javalin.openapi.plugin.redoc.ReDocPlugin
import io.javalin.openapi.plugin.swagger.SwaggerPlugin
import java.util.concurrent.atomic.AtomicInteger

data class User(
    val id: Int,
    val name: String,
    val email: String
)

object UserService {

    private val users = hashMapOf(
        0 to User(id = 0, name = "Alice", email = "alice@alice.kt"),
        1 to User(id = 1, name = "Bob", email = "bob@bob.kt"),
        2 to User(id = 2, name = "Carol", email = "carol@carol.kt"),
        3 to User(id = 3, name = "Dave", email = "dave@dave.kt")
    )

    private var lastId: AtomicInteger = AtomicInteger(users.size - 1)

    fun getAll() = users.values
}

fun getConfiguredOpenApiPlugin(): OpenApiPlugin {
    return OpenApiPlugin { pluginConfig ->
        pluginConfig.withDefinitionConfiguration { _, definition ->
            definition.withInfo { info: OpenApiInfo ->
                info.title = "sentinel"
                info.version = "1.0.0"
                info.description = "sentinel"
            }
        }
        pluginConfig.documentationPath = "/swagger-docs"
    }
}

object UserController {
    @OpenApi(
        summary = "Get all users",
        operationId = "getAllUsers",
        tags = ["User"],
        responses = [OpenApiResponse("200", [OpenApiContent(Array<User>::class)])],
        path = "/users",
        methods = [HttpMethod.GET]
    )
    fun getAll(ctx: Context) {
        ctx.json(UserService.getAll())
    }
}
fun main() {

    Javalin.create { config ->
        config.registerPlugin(OpenApiPlugin { pluginConfig ->
            pluginConfig.withDefinitionConfiguration { version, definition ->
                definition.withInfo { info: OpenApiInfo ->
                    info.title = "Javalin OpenAPI example"
                }
            }
        })
        config.registerPlugin(SwaggerPlugin())
        config.registerPlugin(ReDocPlugin())
        config.router.apiBuilder {
            path("users") {
                get(UserController::getAll);
            }
        }
    }.start(7001)

    println("Check out ReDoc docs at http://localhost:7001/redoc")
    println("Check out Swagger UI docs at http://localhost:7001/swagger")

}

pom.xml配置 #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>untitled</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>11</java.version>
        <kotlin.version>1.9.22</kotlin.version>
        <kotlin.code.style>official</kotlin.code.style>
        <javalin.version>6.1.0</version>
    </properties>

    <dependencies>
        <!-- Kotlin -->
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-stdlib</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-reflect</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-stdlib-common</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-test</artifactId>
            <version>${kotlin.version}</version>
            <scope>test</scope>
        </dependency>

        <!-- Javalin -->
        <dependency>
            <groupId>io.javalin</groupId>
            <artifactId>javalin-bundle</artifactId>
            <version>${javalin.version}</version>
        </dependency>

        <dependency>
            <groupId>io.javalin.community.openapi</groupId>
            <artifactId>javalin-openapi-plugin</artifactId>
            <version>${javalin.version}</version>
        </dependency>
        <dependency>
            <groupId>io.javalin.community.openapi</groupId>
            <artifactId>javalin-swagger-plugin</artifactId>
            <version>${javalin.version}</version>
        </dependency>
        <dependency>
            <groupId>io.javalin.community.openapi</groupId>
            <artifactId>javalin-redoc-plugin</artifactId>
            <version>${javalin.version}</version>
        </dependency>

    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-maven-plugin</artifactId>
                <version>${kotlin.version}</version>
                <configuration>
                    <jvmTarget>11</jvmTarget>
                </configuration>
                <executions>
                    <execution>
                        <id>compile</id>
                        <phase>process-sources</phase>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>test-compile</id>
                        <phase>test-compile</phase>
                        <goals>
                            <goal>test-compile</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.10.1</version>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                    <annotationProcessorPaths>
                        <annotationProcessorPath>
                            <groupId>io.javalin.community.openapi</groupId>
                            <artifactId>openapi-annotation-processor</artifactId>
                            <version>6.0.0-SNAPSHOT</version>
                        </annotationProcessorPath>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>5.1.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <generatorName>kotlin</generatorName>
                            <inputSpec>${project.basedir}/src/main/resources/openapi.json</inputSpec>
                            <configOptions>
                                <sourceFolder>src/gen/java/main</sourceFolder>
                            </configOptions>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

错误截图 #

问题原因及解决办法 #

1. 注解处理器版本不匹配 #

pom.xml中openapi-annotation-processor版本为6.0.0-SNAPSHOT，与Javalin的6.1.0版本不一致，导致注解无法被正确解析。修改为与Javalin版本一致：

<annotationProcessorPath>
    <groupId>io.javalin.community.openapi</groupId>
    <artifactId>openapi-annotation-processor</artifactId>
    <version>${javalin.version}</version>
</annotationProcessorPath>

2. 配置Kotlin注解处理器 #

Kotlin代码的注解需要通过Kotlin插件的kapt处理，仅配置maven-compiler-plugin无效。修改kotlin-maven-plugin添加kapt配置：

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <version>${kotlin.version}</version>
    <configuration>
        <jvmTarget>11</jvmTarget>
    </configuration>
    <executions>
        <!-- 保留原有compile、test-compile执行配置 -->
        <execution>
            <id>kapt</id>
            <goals>
                <goal>kapt</goal>
            </goals>
            <configuration>
                <annotationProcessorPaths>
                    <annotationProcessorPath>
                        <groupId>io.javalin.community.openapi</groupId>
                        <artifactId>openapi-annotation-processor</artifactId>
                        <version>${javalin.version}</version>
                    </annotationProcessorPath>
                </annotationProcessorPaths>
            </configuration>
        </execution>
    </executions>
</plugin>

完成后可移除maven-compiler-plugin中的注解处理器配置，避免重复。

3. 统一OpenAPI文档路径 #

若自定义了documentationPath，需确保Swagger/ReDoc插件指向正确路径。示例中main方法注册的OpenApiPlugin未设置路径，默认是/openapi.json，可统一配置：

config.registerPlugin(OpenApiPlugin { pluginConfig ->
    pluginConfig.withDefinitionConfiguration { version, definition ->
        definition.withInfo { info: OpenApiInfo ->
            info.title = "Javalin OpenAPI example"
            info.version = "1.0.0"
        }
    }
    pluginConfig.documentationPath = "/swagger-docs"
})
// SwaggerPlugin需指定自定义路径
config.registerPlugin(SwaggerPlugin {
    it.specUrl = "/swagger-docs"
})

4. 移除冗余依赖 #

javalin-bundle已包含所有OpenAPI相关插件，无需单独引入javalin-openapi-plugin、javalin-swagger-plugin、javalin-redoc-plugin，删除这些依赖可避免版本冲突。

5. 清理重构项目 #

执行mvn clean compile清理旧编译文件，确保注解处理器生成正确的OpenAPI定义，再重新启动项目。

内容的提问来源于stack exchange，提问作者koda777