如何使用OpenAPI Generator生成Feign Client接口？

问题描述 #

能否使用OpenAPI Generator生成Feign Client格式的接口？以下是我的Gradle配置、当前生成的接口以及期望的格式：

当前Gradle配置 #

plugins {
    id 'java'
    id 'org.springframework.boot' version '2.7.11'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id "org.openapi.generator" version "6.3.0"
}

group = 'dev.rifaii'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.cloud:spring-cloud-starter-openfeign:4.0.2'

    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

def swaggerCodeGenConfig = {
    generatorName = "spring"
    remoteInputSpec = "someUrl"
    outputDir = "$projectDir/external/src/main/java"
    apiPackage = 'somepackageForApis'
    modelPackage = 'somepackageForModels'
    additionalProperties = [
            packageName: "petstore",
            interfaceOnly: 'true',
            feign      : 'true'
    ]
}


task buildExampleClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
    configure swaggerCodeGenConfig
    remoteInputSpec = "http://158.101.191.70:8081/v3/api-docs"
    apiPackage = 'dev.rifaii.example.api'
    modelPackage = 'dev.rifaii.example.model'
}

当前生成的接口 #

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2023-05-09T00:05:09.505990300+03:00[Europe/Tallinn]")
@Validated
@Tag(name = "store", description = "the store API")
public interface StoreApi {

    default Optional<NativeWebRequest> getRequest() {
        return Optional.empty();
    }

    /**
     * DELETE /store/order/{orderId} : Delete purchase order by ID
     * For valid response try integer IDs with value &lt; 1000. Anything above 1000 or nonintegers will generate API errors
     *
     * @param orderId ID of the order that needs to be deleted (required)
     * @return Invalid ID supplied (status code 400)
     *         or Order not found (status code 404)
     */
    @Operation(
        operationId = "deleteOrder",
        summary = "Delete purchase order by ID",
        description = "For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors",
        tags = { "store" },
        responses = {
            @ApiResponse(responseCode = "400", description = "Invalid ID supplied", content = {
                @Content(mediaType = "*/*", schema = @Schema(implementation = Map.class))
            }),
            @ApiResponse(responseCode = "404", description = "Order not found")
        }
    )
    @RequestMapping(
        method = RequestMethod.DELETE,
        value = "/store/order/{orderId}",
        produces = { "*/*" }
    )
    default ResponseEntity<Void> deleteOrder(
        @Parameter(name = "orderId", description = "ID of the order that needs to be deleted", required = true, in = ParameterIn.PATH) @PathVariable("orderId") Long orderId
    ) {
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

    }
}

期望生成的接口格式 #

@FeignClient("someClient")
public interface SomeClient {
    @RequestMapping(method = RequestMethod.GET, value = "/example")
    List<SomeObject> getExample();
}

之前用旧版Swagger Codegen配合Springfox实现过该需求，但不清楚OpenAPI Generator的配置方式。

解决方案 #

通过调整OpenAPI Generator的配置参数，即可生成符合要求的Feign Client接口，具体修改如下：

1. 更新additionalProperties配置项
   在swaggerCodeGenConfig的additionalProperties中补充以下参数，覆盖原有配置：

   additionalProperties = [
           packageName: "petstore",
           interfaceOnly: 'true',
           feign: 'true',
           // 指定Feign Client的名称，对应@FeignClient注解的参数
           feignClientName: "someClient",
           // 禁用Springfox相关注解，避免生成冗余的@Tag、@Operation等
           useSpringfox: 'false',
           // 移除默认实现方法，生成纯接口
           skipDefaultInterface: 'true',
           // 使用Spring MVC原生注解替代OpenAPI的参数注解
           useSpringMvcAnnotations: 'true'
   ]
   

2. 修改后的完整配置示例
   调整后的swaggerCodeGenConfig如下：

   def swaggerCodeGenConfig = {
       generatorName = "spring"
       remoteInputSpec = "someUrl"
       outputDir = "$projectDir/external/src/main/java"
       apiPackage = 'somepackageForApis'
       modelPackage = 'somepackageForModels'
       additionalProperties = [
               packageName: "petstore",
               interfaceOnly: 'true',
               feign: 'true',
               feignClientName: "someClient",
               useSpringfox: 'false',
               skipDefaultInterface: 'true',
               useSpringMvcAnnotations: 'true'
       ]
   }
   

3. 生成效果说明
   重新执行buildExampleClient任务后，生成的接口会满足以下要求：

   • 自动添加@FeignClient("someClient")注解
   • 移除@Validated、@Tag、@Operation等非必要注解
   • 去掉默认实现方法和getRequest()方法
   • 使用@PathVariable、@RequestParam等Spring MVC原生注解
   • 返回值直接使用业务对象类型（若需保留ResponseEntity，可添加responseEntityReturnType: 'true'参数）

内容的提问来源于stack exchange，提问作者dev-rifaii