使用Kotlin开发GCP Cloud Endpoints执行mvn openApiDocs命令报ClassNotFoundException

endpoints-framework:openApiDocs 目标默认绑定到Maven生命周期的 process-classes 阶段执行，默认配置下Kotlin源码的编译时机晚于该阶段，导致插件扫描类路径时找不到你编写的 com.example.skeleton.TestApi 类。

• 第一步：配置kotlin-maven-plugin将Kotlin编译阶段提前，保证Endpoints插件执行前Kotlin代码已经完成编译
  对应pom.xml配置示例：

  <plugin>
      <groupId>org.jetbrains.kotlin</groupId>
      <artifactId>kotlin-maven-plugin</artifactId>
      <version>${kotlin.version}</version>
      <executions>
          <execution>
              <id>compile</id>
              <phase>process-sources</phase>
              <goals>
                  <goal>compile</goal>
              </goals>
          </execution>
          <execution>
              <id>test-compile</id>
              <phase>process-test-sources</phase>
              <goals>
                  <goal>test-compile</goal>
              </goals>
          </execution>
      </executions>
      <configuration>
          <jvmTarget>11</jvmTarget> <!-- 与项目使用的JDK版本保持一致 -->
      </configuration>
  </plugin>
  

• 第二步：显式给endpoints-framework-maven-plugin配置服务类路径，避免插件从web.xml读取配置失败
  对应pom.xml配置示例：

  <plugin>
      <groupId>com.google.cloud.endpoints</groupId>
      <artifactId>endpoints-framework-maven-plugin</artifactId>
      <version>${endpoints.framework.version}</version>
      <configuration>
          <serviceClasses>
              <param>com.example.skeleton.TestApi</param>
          </serviceClasses>
          <!-- 可选：自定义openapi.json输出目录 -->
          <outputDir>${project.build.directory}/generated-openapi</outputDir>
      </configuration>
      <!-- 可选：显式绑定插件执行到compile阶段之后，进一步确保类已编译 -->
      <executions>
          <execution>
              <phase>compile</phase>
              <goals>
                  <goal>openApiDocs</goal>
              </goals>
          </execution>
      </executions>
  </plugin>
  

• 第三步：检查Kotlin代码的注解与类修饰符

  • 如果编写的是API实现类而非接口，需要给类添加open关键字，Kotlin类默认是final修饰，会导致Endpoints反射访问失败
  • 确保@Api、@ApiMethod、@Named等注解的参数配置正确，示例代码：

  package com.example.skeleton
  
  import com.google.api.server.spi.config.Api
  import com.google.api.server.spi.config.ApiMethod
  import com.google.api.server.spi.config.Named
  
  @Api(
      name = "test",
      version = "v1",
      namespace = @Api.Namespace(
          ownerDomain = "example.com",
          ownerName = "example.com",
          packagePath = ""
      )
  )
  interface TestApi {
      @ApiMethod(name = "sayHello", path = "hello/{name}", httpMethod = ApiMethod.HttpMethod.GET)
      fun sayHello(@Named("name") name: String): String
  }
  

• 第四步：执行正确的Maven命令
  执行命令前先触发编译阶段，命令如下：
  mvn clean compile endpoints-framework:openApiDocs

• 如果是多模块Maven项目，需要在API类所在的子模块目录下执行上述命令
• 确保项目依赖中已经引入了正确版本的endpoints-framework相关依赖，避免类冲突

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