Swagger Codegenにおけるカスタムバリデーションの追加

Swagger（OpenAPI）では必須チェック（required: true）や数値型チェック（type: integer）などが用意されており、コード生成時にバリデーションコードを出力できます。しかし、複雑なバリデーションルールを定義するには正規表現に頼らざるを得ないため、YAMLの保守性が悪化する問題を抱えています。そこで本稿では、Bean Validation Annotationのようなカスタムバリデータを用意し、コード生成時に適切なアノテーションを出力する方法を提案します。

Swaggerでは x- で始まる属性はVendor Extensionsと呼ばれており、APIやモデルを自由に拡張できるようになっています。ここではVendor Extensionsを利用してISBNコードのバリデーションを追加する例を考えます。

まず、Swagger YAMLに独自の属性を追加します。下記の例では x-validations 属性にバリデーションルールのマップを持たせています。

definitions:
  Pet:
    properties:
      code:
        type: string
        x-validations:
          isbn13: true

次に、Swagger CodegenのMustacheテンプレートをカスタマイズします。テンプレートの中では vendorExtensions プロパティでVendor Extensionsにアクセスできます。下記の例では独自のアノテーションを出力しています。

  {{#vendorExtensions.x-validations.isbn13}}
    @ISBN13
  {{/vendorExtensions.x-validations.isbn13}}

Spring MVCテンプレートの場合は、上記のコードを pojo.mustache に追加するとモデルに独自のアノテーションが付くようになります。コード生成を実行すると下記のようなモデルが出力されます。

public class Pet   {
    
  private Long id = null;

    
  private String name = null;

    @ISBN13
  private String code = null;

実際に動く例は下記のリポジトリを参照してください。

github.com