OpenAPI Generatorが内部利用するテンプレートについて

TL; DR

• 言語ごとのテンプレートファイルにOpenAPIの情報を流し込んでソースコード生成
  • テンプレート一覧
• テンプレートは handlebars で記載
  • 利用可能なヘルパー関数（一部Java独自実装あり）: handlebars.java

はじめに

OpenAPI Generatorは、OpenAPIで書かれたAPI仕様からSDK等のソースコードを自動生成できるツールです。非常に多くの言語、フレームワークをサポートしているのが特徴です。

これらのソースコードは、テンプレートファイルを利用して生成されます。
OpenAPI Generatorの実装内部を見る機会があったので、備忘録としてこのテンプレートについてまとめました。

ソースコードのテンプレート

ソースコードは、テンプレートファイルへOpenAPIドキュメントの情報を流し込むことで生成されています。

テンプレート言語には handlebarsが使用されています。

流し込まれる情報には、OpenAPIドキュメントをパースして得られた OpenAPI オブジェクトのフィールドが利用されます。

例：レスポンス CodegenResponse class

使用可能な文法

handlebarsはテンプレート言語mustacheを拡張したもので、制御構文として使える文法 ({{#if}}, {{#each}} 等)が追加されています。

素のmustacheには、「Logic-less templates」の紹介文の通り制御構文や関数は一切定義されていません。ただし、レンダリングを制御するためのユーザー定義関数 (lambda) を実装することが可能です。

（公式より引用）

テンプレート

{{! #hoge ~ /hoge で囲まれた範囲に適用 }}
{{#wrapped}}
  {{name}} is awesome.
{{/wrapped}}

{
  "name": "Willy",
  // lambda定義
  "wrapped": function() {
    return function(text, render) {
      return "<b>" + render(text) + "</b>"
    }
  }
}

結果

<b>Willy is awesome.</b>

handlebars独自の制御構文 (helpers) はこの lambda と同様の文法を持ち、一般的なプログラミング言語のようなif文、ループを記述可能です¹。

公式より引用

<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{else}}
<h1>Unknown Author</h1>
{{/if}}
</div>

OpenAPI GeneratorではhandlebarsのJava実装が使われています。注意点として、Java実装特有のhelperが追加されています　（例: {{#and}}, {{#or}}）。
(公式ページを見ても載っていないので注意！)

構文の挙動を調べる際には、以下のディレクトリを検索するのが確実です。

おわりに

以上、OpenAPI Generatorのテンプレートについての簡単な紹介でした。
拡張機能の親子関係が分かってしまえばなんてことはないのですが、検索途中では「この文法の説明はどこに？？」と沼にはまってしまうことがありました...

1. 文法形式が異なるだけで、mustache自体にも同様の表現力はあります。 ↩