OpenAPI生成DTO与自定义DTO转换的最佳实践问询

方案分析与对比 #

1. 自定义DTO转生成DTO返回 #

• 优势：无需改动OpenAPI生成的核心代码，严格遵循OpenAPI契约，保证接口对外输出与定义一致，契合契约优先的设计理念。
• 劣势：需编写字段转换逻辑，若DTO字段较多或频繁变动，会增加冗余代码与维护成本。

2. 定制OpenAPI模板生成自定义DTO接口 #

• 优势：从生成源头解决问题，直接让生成的接口返回自定义DTO，避免转换步骤。
• 劣势：需要掌握OpenAPI Generator的模板语法（如Mustache），后续OpenAPI版本升级可能需要适配模板，灵活性较低。

3. 其他优化方案 #

• 调整OpenAPI规范：如果有权限修改OpenAPI文档，可将自定义DTO的字段补充到规范中，让生成的DTO与自定义DTO结构完全对齐，从根源消除转换需求。
• 使用自动转换工具：结合MapStruct等工具自动生成转换代码，减少手动编写转换逻辑的工作量，同时降低出错概率。

推荐最佳实践 #

1. 契约优先场景：优先选择「自定义DTO转生成DTO」+ MapStruct自动转换，既保证契约一致性，又减少手动代码量。
2. 自定义DTO与契约差异大：若自定义DTO包含大量契约外字段，且无需严格遵循对外契约，可定制OpenAPI模板直接生成返回自定义DTO的接口。
3. 可修改OpenAPI规范：优先调整规范让生成的DTO匹配自定义需求，这是最简洁的解决方案，无需额外转换或模板维护。

代码改进示例 #

示例1：MapStruct自动转换实现方案 #

1. 添加MapStruct依赖（Maven）

<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.5.Final</version>
    <scope>provided</scope>
</dependency>

2. 编写转换映射器

import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;

@Mapper(componentModel = "spring")
public interface PriceDtoConverter {
    PriceDtoConverter INSTANCE = Mappers.getMapper(PriceDtoConverter.class);

    // 自定义DTO转生成DTO
    PriceDto customToGenerated(CustomPriceDto customPriceDto);
}

3. 控制器中使用转换

@RestController
public class PriceController implements PriceControllerApi {
    private final PriceService priceService;
    private final PriceDtoConverter converter;

    // 构造注入
    public PriceController(PriceService priceService, PriceDtoConverter converter) {
        this.priceService = priceService;
        this.converter = converter;
    }

    @Override
    public ResponseEntity<PriceDto> getPrice(Long id) {
        CustomPriceDto customDto = priceService.getCustomPrice(id);
        PriceDto generatedDto = converter.customToGenerated(customDto);
        return ResponseEntity.ok(generatedDto);
    }
}

示例2：定制OpenAPI模板方案 #

1. 修改Spring Controller模板（controller.mustache）

找到OpenAPI Generator默认的controller.mustache模板，将返回类型替换为自定义DTO：

{{#returnType}}
ResponseEntity<com.yourproject.dto.CustomPriceDto> {{operationId}}({{#allParams}}{{>queryParams}}{{/allParams}});
{{/returnType}}

2. 生成代码时指定模板目录

openapi-generator generate -i openapi.yaml -g spring -o ./generated-code --template-dir ./custom-templates

示例3：调整OpenAPI规范方案 #

在openapi.yaml中补充自定义字段，让生成的DTO与自定义DTO对齐：

components:
  schemas:
    PriceDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        amount:
          type: number
          format: decimal
        currencyCode:
          type: string
        # 添加自定义字段
        discount:
          type: number
          format: decimal

生成后直接使用该DTO，无需自定义额外的DTO类。

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