Nablarch OpenAPI Generator

ツールの概要

Nablarch OpenAPI Generatorは、 OpenAPI(外部サイト、英語) ドキュメントからソースコードを生成する OpenAPI Generator(外部サイト、英語) のGenerator実装である。

本ツールはNablarch RESTfulウェブサービス用のGeneratorを提供しており、 OpenAPI GeneratorのMavenプラグイン(外部サイト、英語) に組み込み実行することでソースコードを生成する。

生成されたソースコードを使用することで、OpenAPIドキュメントで定義したREST APIのインターフェースに従ったアクションクラスの実装が容易となる。

前提条件

  • Nablarch RESTfulウェブサービスのソースコード生成元となるOpenAPIドキュメントが作成されていること
  • OpenAPIドキュメントは OpenAPI 3.0.3(外部サイト、英語) 仕様で記述されていること

動作概要

本ツールではソースコード生成元となるOpenAPIドキュメントを入力として指定することで、OpenAPIドキュメントから以下のソースコードを生成する。

  • パスおよびオペレーション定義を元にした、リソース(アクション)インターフェース
  • スキーマ定義を元にした、リクエスト、レスポンスに対応するモデル

補足

OpenAPI Generatorの仕様上 .openapi-generator-ignore.openapi-generator/FILES.openapi-generator/VERSIONGeneratorの設定項目output で指定したディレクトリ配下に生成されるが、これらは使用しない。

運用方法

本ツールは以下の運用方法を想定している。

  1. ウェブサービスの設計情報を元にOpenAPIドキュメントを作成する
  2. Nablarch RESTfulウェブサービスのプロジェクトを作成し、MavenプラグインとしてOpenAPI Generatorおよび本ツールの設定を行う
  3. プロジェクトをビルドし、リソース(アクション)インターフェースとモデルを生成する
  4. 生成したリソース(アクション)インターフェースとモデルを使用して、Nablarch RESTfulウェブサービスの実装を行う

補足

本ツールはOpenAPIドキュメントの修正に合わせて繰り返し実行されることを想定している。Nablarch RESTfulウェブサービスのアクションクラスは生成されたリソース(アクション)インターフェースを実装して作成するため、本ツールによる自動生成を再度行ってもアクションクラスに実装した内容が失われることはない。

補足

OpenAPI Generatorおよび本ツールはMavenプラグインとしての実行形態を想定しているが、CLIでも使用可能である。詳しくは CLIとして実行する を参照すること。

使用方法

Mavenプラグインの設定

本ツールを使用するために最低限必要な、OpenAPI GeneratorのMavenプラグインの設定例を以下に示す。

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>7.10.0</version>
  <dependencies>
    <!-- 本ツールのモジュールを依存関係に追加 -->
    <dependency>
      <groupId>com.nablarch.tool</groupId>
      <artifactId>nablarch-openapi-generator</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <!-- OpenAPIドキュメントのファイルパスを指定する -->
        <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
        <generatorName>nablarch-jaxrs</generatorName>
        <configOptions>
          <sourceFolder>src/gen/java</sourceFolder>
          <apiPackage>com.example.api</apiPackage>
          <modelPackage>com.example.model</modelPackage>

          <!-- その他、本ツールのオプションを指定する -->
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

本ツールは以下の依存関係により提供される。

<dependency>
  <groupId>com.nablarch.tool</groupId>
  <artifactId>nablarch-openapi-generator</artifactId>
  <version>1.0.0</version>
</dependency>

OpenAPI GeneratorのMavenプラグインを使用するにあたり、最低限必要な設定はソースコードの生成対象となるOpenAPIドキュメントを指定する inputSpec と、どのGeneratorを使用するかを指定する generatorName の2つである。

generatorName には nablarch-jaxrs を指定することで、本ツールを利用できる。

その他の設定項目については Generatorの設定項目 を参照すること。

補足

本ツールはOpenAPI Generator 7.10.0を使用して開発、テストをしている。 OpenAPI Generatorのバージョンを変更する場合は、プロジェクト側でテストを行い問題ないことを確認すること。

実行方法

本ツールはMavenのcompileゴールで実行できる。

mvn compile

なお Generatorの設定項目sourceFolder を明示的に設定した場合、 mvn compile 時に生成されたソースコードをMavenプラグインを設定したプロジェクトのコンパイル対象に含めるようになる。

この動作はOpenAPI GeneratorのMavenプラグインによって行われる。

出力先

OpenAPI GeneratorのMavenプラグインのデフォルト設定では、生成されたソースコードは target/generated-sources/openapi/src/gen/java に出力される。

出力先を変更したい場合は Generatorの設定項目outputsourceFolder を参照すること。

Generatorの設定項目

OpenAPI GeneratorのMavenプラグインの主要な設定項目を以下に示す。これらは configuration タグ内直下のタグとして指定する。

項目名 設定内容 必須/任意 デフォルト値
inputSpec 入力となるOpenAPIドキュメントのファイルパスを指定する。 必須 なし
generatorName ソースコードを生成するGeneratorの名前を指定する。
本ツールでは nablarch-jarxrs と指定すること。
必須 なし
output ソースコードの生成先ディレクトリを指定する。 任意 generated-sources/openapi

本ツールの設定項目を以下に示す。すべて任意項目であり、これらは configOptions タグ内に指定する。

項目名 設定内容 デフォルト値
apiPackage 生成するリソース(アクション)インターフェースのパッケージを
指定する。
org.openapitools.api
modelPackage 生成するモデルのパッケージを指定する。 org.openapitools.model
hideGenerationTimestamp Generated アノテーションを注釈する時に date 属性を
付与するか否か。デフォルトではソースコードを生成した日時が
出力される。
false
sourceFolder ソースコードの生成先ディレクトリを指定する。
OpenAPI GeneratorのMavenプラグイン設定の output からの
相対パスとして解釈される。
この項目を指定すると、本ツールにより生成したソースコードが
mvn compile 時のコンパイル対象に含まれるようになる。
src/gen/java
useTags 生成するリソース(アクション)インターフェースの単位を
パスではなくエンドポイントに付与されているタグの単位とする。
なお、エンドポイントに複数のタグが付与されている場合は最初の
タグが有効となる。
false
serializableModel 生成するモデルに java.io.Serializable
インターフェースを実装する。
false
generateBuilders モデルに対するビルダークラスを生成する。 false
useBeanValidation OpenAPIドキュメントのバリデーション定義から、
Bean Validation の機能を使った
バリデーションを行うようにソースコードを生成する。
false
additionalModelTypeAnnotations 生成するモデルのクラス宣言に追加のアノテーションを注釈する。
複数のアノテーションを追加する場合は ; 区切りで指定する。
なし
additionalEnumTypeAnnotations 生成するenum型に追加のアノテーションを注釈する。
複数のアノテーションを追加する場合は ; 区切りで指定する。
なし
primitivePropertiesAsString モデルのプリミティブなデータ型のプロパティをすべて
String として出力する。
false
supportConsumesMediaTypes 生成するリソース(アクション)インターフェースがリクエストを
受け付けるメディアタイプを , 区切りで指定する。
application/json,multipart/form-data
supportProducesMediaTypes 生成するリソース(アクション)インターフェースがレスポンス
とするメディアタイプを , 区切りで指定する。
application/json

Bean Validationを使用するソースコードを生成する

Bean Validation を使用するようにソースコードを生成する場合は、 useBeanValidation の値を true に設定する。

以下に設定例を示す。

<configuration>
  <!-- OpenAPIドキュメントのファイルパスを指定する -->
  <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
  <generatorName>nablarch-jaxrs</generatorName>
  <configOptions>
    <sourceFolder>src/gen/java</sourceFolder>
    <apiPackage>com.example.api</apiPackage>
    <modelPackage>com.example.model</modelPackage>

    <!-- Bean Validationを使用するソースコードを生成する -->
    <useBeanValidation>true</useBeanValidation>
  </configOptions>
</configuration>

useBeanValidation のデフォルト値は false のため、デフォルトでは Bean Validation の機能を使用するアノテーションは注釈されない。

これは、OpenAPI仕様にて規定されてるバリデーション定義では業務要件を満たせないことが多いと考えられ、また相関バリデーションの定義も行えないためである。

このような観点も含め、バリデーション機能を使用するようにソースコード生成する場合の仕様や運用上の注意点は OpenAPIドキュメントのバリデーション定義とBean Validationの対応仕様 に詳細に記載しているので参照すること。

CLIとして実行する

本ツールは主にMavenプラグインとして使用することを想定しているが、CLIとしても使用可能である。ここでは補足としてCLIでの実行方法を紹介する。

CLIとして実行するには、 OpenAPI Generator 7.10.0のJARファイル(外部サイト) および 本ツールのJARファイル(外部サイト) をダウンロードしてjavaコマンドで実行する。実行例を以下に示す。

java -cp openapi-generator-cli-7.10.0.jar:nablarch-openapi-generator-1.0.0.jar org.openapitools.codegen.OpenAPIGenerator generate --generator-name nablarch-jaxrs --input-spec openapi.yaml --output out --additional-properties=apiPackage=com.example.api,modelPackage=com.example.model,useBeanValidation=true,hideGenerationTimestamp=true

--generator-name には nablarch-jaxrs を指定する。 Generatorの設定項目 のうちOpenAPI Generatorの設定項目はOpenAPI GeneratorのCLIでも指定できる。詳しくは以下のコマンドの結果を参照。

java -jar openapi-generator-cli-7.10.0.jar help generate

補足

OpenAPI Generatorの設定項目は、 --generator-name のようにハイフン区切りの形式になる。

Generatorの設定項目 のうち本ツール固有の設定項目については、 --additional-propertieskey=value の形式で指定する。複数指定する場合は , 区切りでの指定となる。

補足

本ツール固有の設定項目は、 --additional-properties=hideGenerationTimestamp=true のように --additional-properties= に続けて項目名をそのまま指定する。

ソースコード生成仕様

以降では、本ツールがOpenAPIドキュメントを元にソースコードを生成する仕様について記載する。

重要

Nablarch RESTfulウェブサービスはJakarta RESTful Web Servicesが提供するすべてのアノテーションをサポートしているわけではないため、ここで記載する内容以外のOpenAPIドキュメントの内容は生成されるソースコードに反映されないことに注意すること。

Nablarch RESTfulウェブサービスがサポートしているアノテーションについては アーキテクチャ概要 および、ルーティングアダプタの Jakarta RESTful Web ServicesのPathアノテーションでマッピングする を参照すること。

リソース(アクション)インターフェース生成仕様

ここではリソース(アクション)インターフェースの生成仕様を記載する。 リソースクラスのメソッドのシグネチャ に則った形で生成するのでこちらも参照すること。

リソース(アクション)インターフェースの生成単位や型定義に関する仕様を以下に示す。

  • OpenAPIドキュメントに定義されたパスおよびオペレーションの情報を元に生成する。
  • Javaのインターフェースとして生成する。
  • リソース(アクション)インターフェースの生成単位は、以下から選択する。
    • デフォルトではOpenAPIドキュメントのパスの第一階層でまとめられたものとなる。
    • useTagstrue にした場合はオペレーションに付与されているタグの単位となる。
  • リソース(アクション)インターフェースの宣言には Path アノテーションを注釈する。
  • Generated アノテーションを注釈する。

リソース(アクション)インターフェースのメソッド生成に関する仕様を以下に示す。

メソッド宣言に注釈するアノテーション

アノテーション 説明
GET オペレーションのHTTPメソッドがGETの場合に注釈する。
POST オペレーションのHTTPメソッドがPOSTの場合に注釈する。
PUT オペレーションのHTTPメソッドがPUTの場合に注釈する。
DELETE オペレーションのHTTPメソッドがDELETEの場合に注釈する。
PATCH オペレーションのHTTPメソッドがPATCHの場合に注釈する。
HEAD オペレーションのHTTPメソッドがHEADの場合に注釈する。
OPTIONS オペレーションのHTTPメソッドがOPTIONSの場合に注釈する。
Consumes リクエストのコンテンツタイプがある場合に注釈する。
Produces レスポンスのコンテンツタイプがあり、 type: string かつ format: binary 以外の場合に注釈する。
Valid リクエストボディがあり、 useBeanValidationtrue の場合に注釈する。

補足

type: string かつ format: binary はファイルダウンロードを意味しており、この場合のコンテンツタイプは HttpResponse#setContentType を使用して設定する。

メソッド名の生成仕様

  • OpenAPIドキュメントの operationId 要素の値をメソッド名として使用する。
  • operationId 要素が指定されていない場合は、 パスの値とHTTPメソッド名を組み合わせてメソッド名を生成する。

メソッド引数の生成仕様

メソッド引数の型 説明
リクエストモデルの型 リクエストボディを受け取り、かつリクエストのコンテンツタイプがマルチパート以外の場合、対応するモデルの型の引数を設定する。
JaxRsHttpRequest 常に生成し、引数に設定する。
ExecutionContext 常に生成し、引数に設定する。

補足

  • RESTfulウェブサービスはJakarta RESTful Web Servicesで規定されている PathParamQueryParam 等には対応していないため、 parameters の定義はメソッド引数には反映されない。これらの情報は JaxRsHttpRequest より取得すること。
  • リクエストのコンテンツタイプが multipart/form-data の場合は、リクエストモデルの型の引数は生成されない。アップロードされたファイルは JaxRsHttpRequest より取得すること。

メソッド戻り値の生成仕様

メソッド戻り値の型 説明
EntityResponse レスポンスがモデルの場合に生成する。型パラメータにはモデルの型を反映する。
HttpResponse レスポンスがモデルでない場合やHTTPステータスコードが 200 以外の場合に生成する。

モデル生成仕様

モデルの生成単位や型定義に関する仕様を以下に示す。

  • スキーマとして定義しているモデルに対して生成する。
  • Javaのクラスとして生成する。
  • JsonTypeName アノテーションを注釈する。
  • Generated アノテーションを注釈する。

モデルのプロパティに関する生成仕様を以下に示す。

  • OpenAPIドキュメントのスキーマに定義されたフィールドに対応するプロパティを生成する。
  • プロパティに対するgetterおよびsetterを生成し、 JsonProperty アノテーションを注釈する。
  • プロパティの値を設定してモデル自身の型を返す、メソッドチェインが可能なメソッドを生成する。
  • useBeanValidationtrue かつOpenAPIドキュメントにバリデーション定義がある場合、 Bean Validation を使用したバリデーションを有効にする。
  • バリデーションで使用するアノテーションは、Nablarchの提供する Bean Validation 固有のものとJakarta EE標準の jakarta.validation.constraints パッケージのものを使用する。

OpenAPIドキュメントでのデータ型やフォーマットとJavaのデータ型との対応仕様は OpenAPIドキュメントのデータ型およびフォーマットとJavaのデータ型の対応仕様 、バリデーション定義とバリデーションで使用するアノテーションの対応仕様は OpenAPIドキュメントのバリデーション定義とBean Validationの対応仕様 に記載する。

モデルのその他の生成仕様を以下に示す。

  • hashCodeequalstoString メソッドを生成する。

生成されるソースコードが依存するモジュール

本ツールで生成されるソースコードをビルドするには、依存関係に以下のモジュールが必要になる。

<dependency>
  <groupId>com.nablarch.framework</groupId>
  <artifactId>nablarch-fw-jaxrs</artifactId>
</dependency>
<dependency>
   <groupId>com.nablarch.framework</groupId>
   <artifactId>nablarch-core-validation-ee</artifactId>
</dependency>
<dependency>
  <groupId>jakarta.ws.rs</groupId>
  <artifactId>jakarta.ws.rs-api</artifactId>
</dependency>
<dependency>
  <groupId>jakarta.annotation</groupId>
  <artifactId>jakarta.annotation-api</artifactId>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-annotations</artifactId>
  <version>2.17.1</version>
</dependency>

RESTfulウェブサービスのブランクプロジェクトに設定されている依存関係にはこれらはすべて含まれている。

OpenAPIドキュメントのデータ型およびフォーマットとJavaのデータ型の対応仕様

OpenAPIドキュメント上で定義されたデータ型とフォーマットに対して、本ツールによるJavaのデータ型の対応表を以下に示す。

OpenAPIでのデータ型( type ) OpenAPIでのフォーマット( format ) モデルのプロパティのデータ型
integer   java.lang.Integer
integer int32 java.lang.Integer
integer int64 java.lang.Long
number   java.math.BigDecimal
number float java.lang.Float
number double java.lang.Double
boolean   java.lang.Boolean
string   java.lang.String
string byte byte[]
string date java.time.LocalDate
string date-time java.time.OffsetDateTime
string number java.math.BigDecimal
string uuid java.util.UUID
string uri java.net.URI
string   enum ( enum を指定すると対応するEnum型を生成する )
array   java.util.List
array   java.util.Set ( uniqueItems: true の場合)
object   対応するモデルの型
object   対応する型がない場合は java.lang.Object

補足

  • type: string かつ format: binary はリクエストのコンテンツタイプが multipart/form-data の場合のみ利用可能で、それ以外コンテンツタイプやレスポンスのモデル定義内で使用した場合はモデルの生成を中止する。
  • type: string の場合は上記表以外にも多数のフォーマットがあるが、すべて java.lang.String として生成する。

OpenAPIドキュメントのバリデーション定義とBean Validationの対応仕様

本ツールでは useBeanValidation のデフォルト値が false のためOpenAPIドキュメントの定義に関わらずデフォルトでは Bean Validation で使用するアノテーションは注釈しないが、 true とした場合はOpenAPIドキュメントの記述内容によって以下の2つの方針でプロパティにアノテーションを注釈する。

  • OpenAPI仕様にて規定されているプロパティに対応するバリデーション
  • ドメインバリデーション

OpenAPI仕様にて規定されているプロパティに対応するバリデーション

OpenAPI仕様にて規定されているプロパティ(外部サイト、英語) を使用してバリデーション定義を行った場合、以下の対応表に沿ってアノテーションを注釈する。

OpenAPIでのデータ型( type ) OpenAPIでのフォーマット( format ) OpenAPIで使用しているプロパティ 注釈するバリデーション用のアノテーション
integer (フォーマットは問わない) required Required
integer   minimum および maximum NumberRange(min = {minimum}, max = {maximum})
integer int32 required Required
integer int32 minimum および maximum NumberRange(min = {minimum}, max = {maximum})
integer int64 required Required
integer int64 minimum および maximum NumberRange(min = {minimum}, max = {maximum})
number (フォーマットは問わない) required Required
number   minimum および maximum DecimalRange(min = “{minimum}”, max = “{maximum}”)
number float required Required
number float minimum および maximum DecimalRange(min = “{minimum}”, max = “{maximum}”)
number double required Required
number double minimum および maximum DecimalRange(min = “{minimum}”, max = “{maximum}”)
boolean   required Required
string (フォーマットは問わない) required Required
string   minLength および maxLength Length(min = {minLength}, max = {maxLength})
string   pattern Pattern(regexp = “{pattern}”)
array   required Required
array   minItems および maxItems Size(min = {minItems}, max = {maxItems})

補足

  • multipleOfexclusiveMinimumexclusiveMaximumminPropertiesmaxProperties には対応していない。
  • minimum および maximumminLength および maxLengthminItems および maxItems はどちらか片方だけでも指定可能。
  • Javaのデータ型が java.math.BigDecimaljava.util.Listjava.util.Set またはモデルの場合は Valid アノテーションを注釈する。
  • Pattern のみJakarta Bean Validation標準のアノテーションを注釈し、それ以外はNablarchの提供する Bean Validation 固有のアノテーションを注釈する。

ドメインバリデーション

本ツールでは、 OpenAPI仕様の拡張プロパティ(外部サイト、英語) を使用してOpenAPI仕様では表現できない ドメインバリデーションを使う ことをサポートする。

拡張プロパティには x-nablarch-domain を使用し、値にはドメイン名を指定する。

propertyName:
  type: string
  x-nablarch-domain: "domainName"

useBeanValidationtrue に指定してソースコードを生成すると、対象のプロパティに Domain(“{domainName}”) が注釈される。

なお、ドメインバリデーションには様々なバリデーション定義を含めることができるため、 競合する可能性があるバリデーション定義を検出した場合はソースコードの生成を中止する。これは、ドメインに含まれているバリデーションルールと同じものが指定された場合、重複してバリデーションが行われることになるためである。

具体的には、 x-nablarch-domain を指定したプロパティに対して、 minimummaximumminLengthmaxLengthminItemsmaxItemspattern のいずれかが指定されている場合はソースコードの生成を中止する。

required は必須項目を表しドメイン側で強制するものではないため、併用を可能とする。

バリデーションに関する運用上の注意点

本ツールを使用して、バリデーション定義を含めたソースコードを生成する場合の運用上の注意点を記載する。

OpenAPI仕様の規定範囲では項目単位や相関バリデーションの要求を満たせない場合の注意点

OpenAPI仕様で規定されているバリデーションは必須定義と長さチェック、正規表現によるチェックのみのため、業務アプリケーションが求めるものとしては不足することも想定される。

また自動生成されたソースコードを直接修正することは望ましくないため、ドメインバリデーションを使用しても生成されたモデルに相関バリデーションを実装できない。

このため、OpenAPI仕様や本ツールのカバー範囲ではバリデーションの要件を満たすことができず別途実装が必要となり、結果として自動生成したモデルと手動で実装したフォーム等でバリデーション定義が分散されやすい状況になることに注意すること。

自動生成したモデルにはバリデーション定義を含めない場合の実装方法

ここでは、バリデーション定義として自動生成したモデルと同じ定義のフォーム等を作成し、 BeanUtil を使用してプロパティ値をコピー後、バリデーションを実施する方法を紹介する。

本ツールがデフォルトでバリデーション用のアノテーションを注釈しないのは、前述のとおりバリデーション定義が分散される状況が生まれやすいことを想定しており、それは望ましくないと考えているからである。

考え方としては バリデーションの明示的な実行 と同様で、実装イメージを以下に記載する。

public class ProjectAction implements ProjectsApi {  // ProjectsApiは本ツールで生成したインターフェース

    // インターフェースに定義されたメソッドを実装
    @Override
    public EntityResponse<ProjectResponse> createProject(ProjectCreateRequest projectCreateRequest, JaxRsHttpRequest jaxRsHttpRequest, ExecutionContext context) {
        // モデルと同じプロパティ定義に、単項目バリデーションや相関バリデーションを加えたフォーム
        ProjectCreateForm form;

        try {
            // ユーティリティクラス内でモデルからフォームに値をコピーした後、バリデーションを明示的に実行する
            form = ProjectValidatorUtil.validate(ProjectCreateForm.class, projectCreateRequest);
        } catch (ApplicationException e) {
            // バリデーションエラー時に任意の処理を行う
            // ...

            throw e;
        }

        // 省略

        return response;
    }
}

// ユーティリティクラスのイメージ
public final class ProjectValidatorUtil {
    // その他の処理は省略

    /**
     * HTTPリクエストからBeanを生成し、バリデーションを行う。
     *
     * @param beanClass 生成したいBeanクラス
     * @param src プロパティのコピー元オブジェクト
     * @return  プロパティに値が登録されたBeanオブジェクト
     */
    public static <T> T validate(Class<T> beanClass, Object src) {
        T bean = BeanUtil.createAndCopy(beanClass, src));
        ValidatorUtil.validate(bean);
        return bean;
    }
}

ドメインバリデーションを使用する場合の注意点

ドメインバリデーションを使用すると、モデルのプロパティに対するドメインを定義することでバリデーション定義をまとめたりOpenAPI仕様でサポートしていないバリデーションを使用できる。

ただしOpenAPI仕様でサポートしているバリデーション範囲も含めてバリデーション仕様がドメイン側に隠蔽されやすくなり、OpenAPIドキュメントからバリデーション仕様が見えなくなる可能性がある点に注意すること。

OpenAPIドキュメントと生成されるソースコードの例

以下に、OpenAPIドキュメントと生成されるソースコードの例を記載する。

ソースコード生成時の本ツールの設定例は以下とする。この設定と異なる設定項目が必要になる例では、本ツールの設定例も併記する。

<configuration>
  <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
  <generatorName>nablarch-jaxrs</generatorName>
  <configOptions>
    <sourceFolder>src/gen/java</sourceFolder>
    <apiPackage>com.example.api</apiPackage>
    <modelPackage>com.example.model</modelPackage>
  </configOptions>
</configuration>

なお、記載している各種例はイメージを掴むことを目的とするため抜粋での記載としている。

OpenAPIドキュメントのパスおよびオペレーションの定義とソースコードの生成例

OpenAPIドキュメント例

/projects:
  post:
    tags:
    - project
    summary: プロジェクトを登録する
    description: プロジェクトを登録する
    operationId: createProject
    requestBody:
      description: プロジェクト登録情報
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProjectCreateRequest'
    responses:
      "200":
        description: 登録したプロジェクト情報
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectResponse'
/projects/{id}:
  get:
    tags:
    - project
    summary: プロジェクトを取得する
    description: プロジェクトIDを指定してプロジェクトを取得する
    operationId: findProjectById
    parameters:
    - name: id
      in: path
      description: ID
      required: true
      schema:
        type: string
    responses:
      "200":
        description: 取得したプロジェクト情報
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectResponse'
      "404":
        description: プロジェクトが見つからなかった場合

本ツールにより生成されるリソース(アクション)インターフェース例

@Path("/projects")
@jakarta.annotation.Generated(value = "nablarch.tool.openapi.codegen.JavaNablarchJaxrsServerCodegen", date = "2024-12-10T13:54:26.470544738+09:00[Asia/Tokyo]", comments = "Generator version: 7.10.0")
public interface ProjectsApi {
    /**
     * POST  : プロジェクトを登録する
     *
     * プロジェクトを登録する
     *
     * @param projectCreateRequest プロジェクト登録情報
     * @param jaxRsHttpRequest HTTPリクエスト
     * @param context ハンドラ実行コンテキスト
     * @return 登録したプロジェクト情報
     */
    @POST
    @Consumes({ "application/json" })
    @Produces({ "application/json" })
    EntityResponse<ProjectResponse> createProject(ProjectCreateRequest projectCreateRequest, JaxRsHttpRequest jaxRsHttpRequest, ExecutionContext context);

    /**
     * GET /{id} : プロジェクトを取得する
     *
     * プロジェクトIDを指定してプロジェクトを取得する
     *
     * @param jaxRsHttpRequest HTTPリクエスト
     * @param context ハンドラ実行コンテキスト
     * @return 取得したプロジェクト情報
     * @return プロジェクトが見つからなかった場合
     */
    @GET
    @Path("/{id}")
    @Produces({ "application/json" })
    EntityResponse<ProjectResponse> findProjectById(JaxRsHttpRequest jaxRsHttpRequest, ExecutionContext context);

}

OpenAPIドキュメントのスキーマの定義とソースコードの生成例

OpenAPIドキュメント例

ProjectResponse:
  description: プロジェクト情報
  type: object
  properties:
    id:
      format: uuid
      description: プロジェクトID
      type: string
    name:
      description: プロジェクト名
      type: string
    sales:
      format: int64
      description: 売上
      type: integer
    startDate:
      format: date
      description: 開始日
      type: string
    endDate:
      format: date
      description: 終了日
      type: string

本ツールにより生成されるモデル例

@JsonTypeName("ProjectResponse")
@jakarta.annotation.Generated(value = "nablarch.tool.openapi.codegen.JavaNablarchJaxrsServerCodegen", date = "2024-12-10T13:54:26.470544738+09:00[Asia/Tokyo]", comments = "Generator version: 7.10.0")
public class ProjectResponse   {
  private UUID id;
  private String name;
  private Long sales;
  private LocalDate startDate;
  private LocalDate endDate;

    /**
     * プロジェクトID
     */
    public ProjectResponse id(UUID id) {
        this.id = id;
        return this;
    }


    @JsonProperty("id")
    public UUID getId() {
        return id;
    }

    @JsonProperty("id")
    public void setId(UUID id) {
        this.id = id;
    }

    /**
     * プロジェクト名
     */
    public ProjectResponse name(String name) {
        this.name = name;
        return this;
    }


    @JsonProperty("name")
    public String getName() {
        return name;
    }

    @JsonProperty("name")
    public void setName(String name) {
        this.name = name;
    }

    /**
     * 売上
     */
    public ProjectResponse sales(Long sales) {
        this.sales = sales;
        return this;
    }


    @JsonProperty("sales")
    public Long getSales() {
        return sales;
    }

    @JsonProperty("sales")
    public void setSales(Long sales) {
        this.sales = sales;
    }

    /**
     * 開始日
     */
    public ProjectResponse startDate(LocalDate startDate) {
        this.startDate = startDate;
        return this;
    }


    @JsonProperty("startDate")
    public LocalDate getStartDate() {
        return startDate;
    }

    @JsonProperty("startDate")
    public void setStartDate(LocalDate startDate) {
        this.startDate = startDate;
    }

    /**
     * 終了日
     */
    public ProjectResponse endDate(LocalDate endDate) {
        this.endDate = endDate;
        return this;
    }


    @JsonProperty("endDate")
    public LocalDate getEndDate() {
        return endDate;
    }

    @JsonProperty("endDate")
    public void setEndDate(LocalDate endDate) {
        this.endDate = endDate;
    }

    // hashCode、equals、toString等は省略
}

Bean Validationを使用するソースコードの生成例

OpenAPIドキュメント例

## パスおよびオペレーション
/projects:
  post:
    tags:
    - project
    summary: プロジェクトを作成する
    description: プロジェクトを作成する
    operationId: createProject
    requestBody:
      description: プロジェクト登録情報
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProjectCreateRequest'
    responses:
      "200":
        description: project created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectResponse'

  ## スキーマ
  ProjectCreateRequest:
    description: プロジェクト作成リクエスト
    required:
    - projectName
    - projectType
    - startDate
    type: object
    properties:
      projectName:
        description: プロジェクト名
        maxLength: 100
        minLength: 1
        type: string
      projectType:
        description: プロジェクト種別
        maxLength: 100
        minLength: 1
        type: string
      startDate:
        format: date
        description: 開始日
        type: string
      endDate:
        format: date
        description: 終了日
        type: string

本ツールの設定例

<configuration>
  <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
  <generatorName>nablarch-jaxrs</generatorName>
  <configOptions>
    <sourceFolder>src/gen/java</sourceFolder>
    <apiPackage>com.example.api</apiPackage>
    <modelPackage>com.example.model</modelPackage>
    <!-- Bean Validationを使用する場合はuseBeanValidationにtrueを指定する -->
    <useBeanValidation>true</useBeanValidation>
  </configOptions>
</configuration>

本ツールにより生成されるリソース(アクション)インターフェース例

@Path("/projects")
@jakarta.annotation.Generated(value = "nablarch.tool.openapi.codegen.JavaNablarchJaxrsServerCodegen", date = "2024-12-10T13:54:26.470544738+09:00[Asia/Tokyo]", comments = "Generator version: 7.10.0")
public interface ProjectsApi {
    /**
     * POST  : プロジェクトを作成する
     *
     * プロジェクトを作成する
     *
     * @param projectCreateRequest プロジェクト登録情報
     * @param jaxRsHttpRequest HTTPリクエスト
     * @param context ハンドラ実行コンテキスト
     * @return project created
     */
    @POST
    @Consumes({ "application/json" })
    @Produces({ "application/json" })
    // HTTPボディでリクエストを受け取る場合に@Validアノテーションが付与される
    @Valid
    EntityResponse<ProjectResponse> createProject(ProjectCreateRequest projectCreateRequest, JaxRsHttpRequest jaxRsHttpRequest, ExecutionContext context);

}

本ツールにより生成されるモデル例

@JsonTypeName("ProjectCreateRequest")
@jakarta.annotation.Generated(value = "nablarch.tool.openapi.codegen.JavaNablarchJaxrsServerCodegen", date = "2024-12-10T13:54:26.470544738+09:00[Asia/Tokyo]", comments = "Generator version: 7.10.0")
public class ProjectCreateRequest   {
  private String projectName;
  private String projectType;
  private LocalDate startDate;
  private LocalDate endDate;

    /**
     * プロジェクト名
     */
    public ProjectCreateRequest projectName(String projectName) {
        this.projectName = projectName;
        return this;
    }


    @JsonProperty("projectName")
    @Required @Length(min = 1, max = 100)
    public String getProjectName() {
        return projectName;
    }

    @JsonProperty("projectName")
    public void setProjectName(String projectName) {
        this.projectName = projectName;
    }

    /**
     * プロジェクト種別
     */
    public ProjectCreateRequest projectType(String projectType) {
        this.projectType = projectType;
        return this;
    }


    @JsonProperty("projectType")
    @Required @Length(min = 1, max = 100)
    public String getProjectType() {
        return projectType;
    }

    @JsonProperty("projectType")
    public void setProjectType(String projectType) {
        this.projectType = projectType;
    }

    /**
     * 開始日
     */
    public ProjectCreateRequest startDate(LocalDate startDate) {
        this.startDate = startDate;
        return this;
    }


    @JsonProperty("startDate")
    @Required
    public LocalDate getStartDate() {
        return startDate;
    }

    @JsonProperty("startDate")
    public void setStartDate(LocalDate startDate) {
        this.startDate = startDate;
    }

    /**
     * 終了日
     */
    public ProjectCreateRequest endDate(LocalDate endDate) {
        this.endDate = endDate;
        return this;
    }


    @JsonProperty("endDate")

    public LocalDate getEndDate() {
        return endDate;
    }

    @JsonProperty("endDate")
    public void setEndDate(LocalDate endDate) {
        this.endDate = endDate;
    }

    // hashCode、equals、toString等は省略
}

ドメインバリデーションを使用するソースコードの生成例

OpenAPIドキュメント例

## パスおよびオペレーション
/projects:
  post:
    tags:
    - project
    summary: プロジェクトを作成する
    description: プロジェクトを作成する
    operationId: createProject
    requestBody:
      description: プロジェクト登録情報
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProjectCreateRequest'
    responses:
      "200":
        description: project created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectResponse'

  ## スキーマ
  ProjectCreateRequest:
    description: プロジェクト作成リクエスト
    required:
    - projectName
    type: object
    properties:
      projectName:
        description: プロジェクト名
        type: string
        ## ドメインバリデーションの使用
        x-nablarch-domain: "projectName"

本ツールの設定例

<configuration>
  <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
  <generatorName>nablarch-jaxrs</generatorName>
  <configOptions>
    <sourceFolder>src/gen/java</sourceFolder>
    <apiPackage>com.example.api</apiPackage>
    <modelPackage>com.example.model</modelPackage>
    <!-- Bean Validationを使用する場合はuseBeanValidationにtrueを指定する -->
    <useBeanValidation>true</useBeanValidation>
  </configOptions>
</configuration>

本ツールにより生成されるモデル例

@JsonTypeName("ProjectCreateRequest")
@jakarta.annotation.Generated(value = "nablarch.tool.openapi.codegen.JavaNablarchJaxrsServerCodegen", date = "2024-12-10T13:54:26.470544738+09:00[Asia/Tokyo]", comments = "Generator version: 7.10.0")
public class ProjectCreateRequest   {
  private String projectName;

    /**
     * プロジェクト名
     */
    public ProjectCreateRequest projectName(String projectName) {
        this.projectName = projectName;
        return this;
    }


    @JsonProperty("projectName")
    @Required @Domain("projectName")
    public String getProjectName() {
        return projectName;
    }

    @JsonProperty("projectName")
    public void setProjectName(String projectName) {
        this.projectName = projectName;
    }

    // hashCode、equals、toString等は省略
}

ファイルアップロードの定義例

OpenAPIドキュメント例

## パスおよびオペレーション
/customers/upload:
  post:
    tags:
    - customer
    summary: 顧客CSVファイルをアップロードする
    description: 顧客CSVファイルをアップロードして顧客情報を取り込む
    operationId: uploadCustomersCsvFile
    requestBody:
      description: 顧客CSVファイル情報
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/CustomersCsvFileUploadRequest'
    responses:
      "200":
        description: 顧客CSVファイルアップロード取り込み結果
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomersCsvFileUploadResultResponse'


  ## スキーマ
  CustomersCsvFileUploadRequest:
    description: 顧客CSVファイル情報
    required:
    - fileName
    - file
    type: object
    properties:
      fileName:
        description: ファイル名
        type: string
      file:
        description: 顧客CSVファイル
        type: string
        format: binary

本ツールにより生成されるリソース(アクション)インターフェース例

@Path("/customers/upload")
@jakarta.annotation.Generated(value = "nablarch.tool.openapi.codegen.JavaNablarchJaxrsServerCodegen", date = "2024-12-10T14:36:36.602623815+09:00[Asia/Tokyo]", comments = "Generator version: 7.10.0")
public interface CustomersApi {
    /**
     * POST  : 顧客CSVファイルをアップロードする
     *
     * 顧客CSVファイルをアップロードして顧客情報を取り込む
     *
     * @param jaxRsHttpRequest HTTPリクエスト
     * @param context ハンドラ実行コンテキスト
     * @return 顧客CSVファイルアップロード取り込み結果
     */
    @POST
    @Consumes({ "multipart/form-data" })
    @Produces({ "application/json" })
    EntityResponse<CustomersCsvFileUploadResultResponse> uploadCustomersCsvFile(JaxRsHttpRequest jaxRsHttpRequest, ExecutionContext context);

}

補足

ファイルアップロードの場合、リクエストのコンテンツタイプには multipart/form-data を指定する。またアップロードファイルには type: string かつ format: binary を指定する。この時、スキーマに対応するモデルのソースコードは生成されない。アップロードされたファイルは JaxRsHttpRequest より取得する。

ファイルダウンロードの定義例

OpenAPIドキュメント例

/customers/upload:
  get:
    tags:
    - customer
    summary: 顧客情報をCSVファイルとしてダウンロードする
    description: 顧客情報をCSVファイルとしてダウンロードする
    operationId: downloadCustomersCsvFile
    responses:
      "200":
        description: 顧客CSVファイル
        content:
          text/csv:
            schema:
              type: string
              format: binary

本ツールにより生成されるリソース(アクション)インターフェース例

@Path("/customers/upload")
@jakarta.annotation.Generated(value = "nablarch.tool.openapi.codegen.JavaNablarchJaxrsServerCodegen", date = "2024-12-10T14:48:03.670170037+09:00[Asia/Tokyo]", comments = "Generator version: 7.10.0")
public interface CustomersApi {
    /**
     * GET  : 顧客情報をCSVファイルとしてダウンロードする
     *
     * 顧客情報をCSVファイルとしてダウンロードする
     *
     * @param jaxRsHttpRequest HTTPリクエスト
     * @param context ハンドラ実行コンテキスト
     * @return 顧客CSVファイル
     */
    @GET
    HttpResponse downloadCustomersCsvFile(JaxRsHttpRequest jaxRsHttpRequest, ExecutionContext context);

}

補足

ファイルダウンロードではレスポンスのコンテンツタイプは任意となる。レスポンスのスキーマ定義は type: string かつ format: binary とし、ダウンロードするファイルの内容やレスポンスヘッダは HttpResponse を使って設定する。