使用OpenAPI Generator生成REST客户端时如何保留校验约束

问题场景 #

我有一个Spring Boot REST服务端，用springdoc-openapi生成OpenAPI描述文件，再通过openapi-generator的typescript-axios生成客户端，但生成的TypeScript DTO丢失了原OpenAPI里的校验规则（比如maxLength、minLength等约束）。

原OpenAPI DTO示例 #

AuftraggeberDTO:
  required:
    - anschrift
    - anzahlNiederlassungen
    - kontaktpersonFuerZulassungsstelle
    - organisationsname
    - validUntil
  type: object
  properties:
    organisationsname:
      maxLength: 1024
      minLength: 0
      type: string
    anschrift:
      $ref: '#/components/schemas/AnschriftDTO'
    telefonnummer:
      maxLength: 1024
      minLength: 0
      type: string
    kontaktpersonFuerZulassungsstelle:
      $ref: '#/components/schemas/KontaktpersonDTO'
    validUntil:
      type: string
      format: date-time
    anzahlNiederlassungen:
      type: integer
      format: int32

生成的TypeScript DTO（丢失校验规则） #

export interface AuftraggeberDTO {
  /**
   *
   * @type {string}
   * @memberof AuftraggeberDTO
   */
  'organisationsname': string;
  /**
   *
   * @type {AnschriftDTO}
   * @memberof AuftraggeberDTO
   */
  'anschrift': AnschriftDTO;
  /**
   *
   * @type {string}
   * @memberof AuftraggeberDTO
   */
  'telefonnummer'?: string;
  /**
   *
   * @type {KontaktpersonDTO}
   * @memberof AuftraggeberDTO
   */
  'kontaktpersonFuerZulassungsstelle': KontaktpersonDTO;
  /**
   *
   * @type {string}
   * @memberof AuftraggeberDTO
   */
  'validUntil': string;
  /**
   *
   * @type {number}
   * @memberof AuftraggeberDTO
   */
  'anzahlNiederlassungen': number;
}

当前Maven插件配置 #

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.5.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>http://localhost:8080/v3/api-docs.yaml</inputSpec>
                <inputSpec>${project.basedir}/src/main/resources/api-description.yaml</inputSpec>
                <generatorName>typescript-axios</generatorName>
                <output>./../vue-client/generated-client/typescript-axios</output>
                <apiPackage>com.example.api</apiPackage>
                <modelPackage>com.example.model</modelPackage>
            </configuration>
        </execution>
    </executions>
</plugin>

解决方案 #

方法1：启用class-validator注解生成（推荐） #

typescript-axios生成器支持直接生成class-validator校验注解，只需修改Maven插件配置，添加对应参数：

修改插件的<configuration>部分，新增<typeMappings>和<configOptions>：

<configuration>
    <!-- 保留原有配置 -->
    <inputSpec>http://localhost:8080/v3/api-docs.yaml</inputSpec>
    <inputSpec>${project.basedir}/src/main/resources/api-description.yaml</inputSpec>
    <generatorName>typescript-axios</generatorName>
    <output>./../vue-client/generated-client/typescript-axios</output>
    <apiPackage>com.example.api</apiPackage>
    <modelPackage>com.example.model</modelPackage>
    
    <!-- 添加以下配置 -->
    <typeMappings>
        <typeMapping>string=string</typeMapping>
        <typeMapping>int32=number</typeMapping>
    </typeMappings>
    <configOptions>
        <!-- 开启class-validator注解生成 -->
        <useClassValidator>true</useClassValidator>
        <!-- 保持属性命名与原OpenAPI一致 -->
        <modelPropertyNaming>original</modelPropertyNaming>
        <!-- 支持ES6语法 -->
        <supportsES6>true</supportsES6>
    </configOptions>
</configuration>

配置后生成的代码会转换为class，并自动带上校验注解，示例如下：

import { IsString, MaxLength, MinLength, IsOptional, IsDateString, IsInt, ValidateNested, IsDefined } from 'class-validator';
import { Type } from 'class-transformer';

export class AuftraggeberDTO {
    /**
     * 
     * @type {string}
     * @memberof AuftraggeberDTO
     */
    @IsString()
    @MaxLength(1024)
    @MinLength(0)
    organisationsname: string;

    /**
     * 
     * @type {AnschriftDTO}
     * @memberof AuftraggeberDTO
     */
    @ValidateNested()
    @Type(() => AnschriftDTO)
    @IsDefined()
    anschrift: AnschriftDTO;

    /**
     * 
     * @type {string}
     * @memberof AuftraggeberDTO
     */
    @IsOptional()
    @IsString()
    @MaxLength(1024)
    @MinLength(0)
    telefonnummer?: string;

    // 其余字段校验注解省略...
}

方法2：自定义OpenAPI Generator模板 #

如果需要更定制化的校验规则输出，可以自定义typescript-axios的模板：

1. 从openapi-generator官方仓库下载typescript-axios的模板文件（如model.mustache）
2. 修改模板，在属性定义处添加校验规则的注释或代码（比如把maxLength、minLength写入JSDoc或直接生成校验逻辑）
3. 在Maven插件配置中通过<templateDirectory>指定自定义模板路径：

<configuration>
    <!-- 原有配置 -->
    <templateDirectory>${project.basedir}/src/main/resources/openapi-templates</templateDirectory>
</configuration>

方法3：手动补充校验逻辑（临时方案） #

如果不想修改生成配置，可在生成的DTO文件基础上手动添加校验规则，或在Vue项目中使用表单校验库（如VeeValidate），基于OpenAPI描述文件手动配置校验规则。但该方法维护成本高，不适合长期使用。

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