openapi-generatorをバージョンアップしたらimportMappingsが動かなくなった

この記事はZOZO Advent Calendar 2022 #4 14日目の記事になります。

はじめに

openapi-generatorをバージョンアップしたらimportMappingsが動かなくなったので原因と対応をまとめます。

openapi-generatorとは

OpenAPI Specificationを元にクライアントやサーバのコードを生成するソフトウェアです。

importMappingsとは

変換に伴いインポートする型のテンプレートを指定するopenapi-generatorの機能です。

何が起こったのか

以下のようなソースを用意しバージョンアップしたopenapi-generatorを実行したところ、
importMappingsが正常に動かない事象が発生しました。

yaml

paths:
  '/user':
    get:
      operationId: getUserList
      summary: |
        ユーザーAPI。
      description: |
        ユーザーリストを取得します。
      parameters:
        - description: |
            ユーザー性別
            1: 男性
            2: 女性
          in: query
          name: gender
          required: false
          schema:
            $ref: '#/components/schemas/gender'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user_response'
          description: 200 (OK)
          headers:
            http_status:
              description: HTTPステータス
              schema:
                type: integer
components:
  schemas:
    gender:
      enum:
        - 1
        - 2
      example: 1
      type: integer
      x-enum-varnames:
        - MEN
        - WOMEN
    user_response:
      example:
        result:
          - name: 山田
        status: 200
      properties:
        result:
          items:
            $ref: '#/components/schemas/user_response'
          type: array
        status:
          example: 200
          format: int32
          type: integer
      type: object
    user_response:
      example:
        name: 山田
      properties:
        name:
          description: 名前
          example: 名前
          type: string
      required:
        - name
      type: object

MemberGender.java

public enum Gender {
  MEN(１),
  WOMEN(２);

  private final Integer value;

  public static Gender of(int value) {
    var match = Arrays.stream(Gender.values()).filter(it -> it.value == value).findFirst();
    return match.orElseThrow(() -> new IllegalArgumentException("誤りがあります:" + value));
  }

  @SneakyThrows
  @JsonCreator
  public static Gender of(String value) {
    return of(Integer.parseInt(value));
  }

  @JsonValue
  public int getValue() {
    return value;
  }
}

build.gradle

openApiGenerate {
    typeMappings = [
            gender: 'com.example.springboot.Gender'
    ]
    importMappings = [
            gender: 'com.example.springboot.Gender'
    ]
{

上記を用意してOpenAPI Generatorによって以下のようなメソッドが生成されていた

    default ResponseEntity<UserResponse> getUserList(@ApiParam(value = "ユーザー性別 1: 男性 2: 女性 ", allowableValues = "1, 2") @Valid @RequestParam(value = "gender", required = false) com.example.springboot.Gender Gender) {
        ....
    }

Genderの型がimportMappingsで指定した「com.example.springboot.Gender」になっている。
ところが、openapi-generatorをバージョンアップしたら以下のようになった

    default ResponseEntity<UserResponse> getUserList(@ApiParam(value = "ユーザー性別 1: 男性 2: 女性 ", allowableValues = "1, 2") @Valid @RequestParam(value = "gender", required = false) Gender Gender) {
        ....
    }

importMappingがうまく動かず型が「Gender」になっている。

原因

openapi-generatorのv5.4.0からimportMappingsが動かなくなるバグが発生しているらしい。

対応

v6.0.0以降で「schemaMappings」で同様のことができるようになった

openApiGenerate {
    typeMappings = [
            gender: 'com.example.springboot.Gender'
    ]
    schemaMappings = [
            gender: 'com.example.springboot.Gender'
    ]
{

上記のように変更したことでテンプレートの指定ができるようになった。

参考にした資料

[BUG][openapi-generator-maven-plugin] importmapping not respected since 5.4.0
【Spring Boot】OpenAPI GeneratorのType Mappingで自作のドメインオブジェクトを使用する