Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Nablarch RESTfulウェブサービス OpenAPI Generatorのドキュメントを追加 #671

Open
wants to merge 20 commits into
base: develop
Choose a base branch
from
Open

Nablarch RESTfulウェブサービス OpenAPI Generatorのドキュメントを追加 #671

wants to merge 20 commits into from
+1,061 −2

Conversation

charon-r13b
Copy link
Contributor

@charon-r13b charon-r13b commented Dec 10, 2024 •
edited
Loading

Nablarch JAX-RS向けのOpenAPI GeneratorのカスタムGeneratorを実装を行った以下のPull Requestに対するドキュメントを作成しました。

nablarch-development-standards/nablarch-development-standards-tools#21

大きく以下の構成にしています。

  • ツールの全体概要
  • 前提条件
  • 動作概要
  • 運用方法
  • 使用方法（プラグインの設定など）
  • ソースコードの生成使用
  • OpenAPIドキュメントと対応するソースコードの生成例

Generatorの設定や、生成内容でどうしても情報過多になりやすいので、表を使いつつ情報量の多い部分は後ろに置くようにしています。

必要な情報は記載していますが、読んでツールの使い方や概要が伝わるかどうかがポイントかなと思っています。

tishijiri
tishijiri reviewed Dec 20, 2024
View reviewed changes
ja/development_tools/toolbox/NablarchJaxrsOpenApiGenerator/NablarchJaxrsOpenApiGenerator.rst Outdated
* パスおよびオペレーション定義を元にした、リソース(アクション)インターフェース
* スキーマ定義を元にした、リクエスト、レスポンスに対応するモデル

また、OpenAPI Generatorのサポートファイル ``.openapi-generator-ignore`` 、 ``.openapi-generator/FILES`` 、 ``.openapi-generator/VERSION`` も生成されるが、これらは使用しない。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

これらのファイルって適当な内容のファイルが作成されるっていうことなんでしょうか？

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.openapi-generator-ignore は固定の内容です。

https://github.com/OpenAPITools/openapi-generator/blob/v7.10.0/modules/openapi-generator/src/main/resources/_common/.openapi-generator-ignore

.openapi-generator/FILESは生成したファイルの一覧、 .openapi-generator/VERSION は使用したOpenAPI Generatorのバージョン（今回であれば 7.10.0 ）が記録されます。

これらはMavenプラグインやCLIの設定では出力を抑制できません。
※書かなくてもいいのではという気はしましたが、生成されるファイルの種類などは書いておいた方がいいのかなと（無視していいよと言ってますが）

Copy link
Contributor

@tishijiri tishijiri Dec 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

あらためて読んでいますと、あくまで補足であるならtipsとかで表記でもよさそうかもと思いました。tipsに書くとしたら「OpenAPI Generatorの仕様上、生成時に〜ファイルが生成されるが、これらは使用しません。」みたいな感じになるんでしょうか。

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tip表記にしてみました。 a40f6c7

tishijiri
tishijiri reviewed Dec 20, 2024
View reviewed changes
ja/development_tools/toolbox/NablarchJaxrsOpenApiGenerator/NablarchJaxrsOpenApiGenerator.rst Outdated
* ``minimum`` および ``maximum`` 、 ``minLength`` および ``maxLength`` 、 ``minItems`` および ``maxItems`` はどちらか片方だけでも指定可能。
* Javaのデータ型が ``java.math.BigDecimal`` 、 ``java.util.List`` 、 ``java.util.Set`` またはモデルの場合は ``Valid`` アノテーションを注釈する。

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ここの部分って重要(important)で案内したほうがよさそうにも思いました。
あと、コード例が無いとどうするのがよいのかイメージつかない様に思えた（私は最初なかなかイメージしづらかった）ので、何か具体例を案内できるとよさそうにも思ったのですが、どうでしょうか？

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bean Validationのページの明示的なバリデーションで考えていました。
これをベースに実装イメージを追記してみました。 dc8b54f

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

（これはいま対応してほしいというコメントではないです）
改めて読んでみて考えてみていたんですが、やはりDomainの対応ができないものか気になりました。
Domainであれば@Domain("キーワード")で出力するだけではあるので、Domainクラス自体は自分で実装してもらうとすれば、x-domain等でキーワードとセットで指定してDomainアノテーションを付与するようにしておくのも有りなのではと思ったりもしました。
（Nablarch採用時はDomainを使うケースが多いと思うので、それができると別でフォームを作らなくてよいケースもかなり多くなりそうにも思えたので）

このPRとは一旦別にして、マージ後にでも改めて相談させていただきたいです。

Copy link
Contributor Author

@charon-r13b charon-r13b Jan 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

改めて読んでみて考えてみていたんですが、やはりDomainの対応ができないものか気になりました。

できることはできると思います。

たとえばこんなイメージになるでしょう。
※ほぼ近い形態で以前実装したので

        projectName:
          type: string
          x-nablarch-constraints:
            domainName: "projectName"

Nablarchのバリデーション用の拡張項目としてx-nablarch-constraintsのようなベンダー拡張プロパティを追加し、その配下にNablarch固有のバリデーションをさらに追加するなどもできると思います。

ですがOpenAPI本来の活用方法とバランスを取るのが難しく、あまり気乗りしないところではあります。
※前に1度考えたことがあります

ドメインバリデーションを採用すると、バリデーションに関するOpenAPIドキュメントの書き方がNablarchのドメイン設定駆動になる気がします。そうすると、おそらく以下の状態になります。

  • OpenAPIドキュメント上からバリデーションの定義がわかりにくくなる
    • これはドメインバリデーションを採用するとバリデーションの定義はおそらく集約されることからの推測です
      • OpenAPI仕様でサポートしているバリデーション（必須、最大値/最小値、長さ、正規表現）もドメイン定義に含まれやすくなると考えられます
      • 結果、OpenAPIドキュメントを見てもドメイン定義がなければバリデーションの内容もわからなくなりインターフェース定義の意味を失いやすくなります
      • またクライアントのGeneratorはベンダー拡張の項目など知らないので、クライアントコードの生成結果に反映されなくなります
    • ドメインバリデーションをサポートするのに、ドメインバリデーションと同じ内容のバリデーション定義をOpenAPIドキュメントに書くこともしないと思います（長さチェックがOpenAPIドキュメントとドメイン定義の両方に入る、など）
      • バリデーションエラーが重複して検出されます
      • Generatorのドメインバリデーションのサポート有無に関わらず、結局別管理というのはそうですが…
    • ドメインバリデーションにはOpenAPIドキュメントでサポートしている範囲は書かない、みたいなこともやりたがらないだろうとは思います
  • OpenAPI仕様の範囲外なので、OpenAPI系のエディタのサポートは得られなくなる

現実的に、ドメインバリデーションをGeneratorのサポート範囲に含め、かつバリデーション用のアノテーションも生成するコードに反映する場合、「ドメインバリデーションにはOpenAPIドキュメントでサポートしている範囲は書かず、OpenAPIドキュメントにのみ記述する」という運用になると思います。

少なくともドメインバリデーションにバリデーションの内容を集約してしまうと、OpenAPIドキュメントから情報が欠落しやすくなるのでここに気を付ける運用になるはずです。

@charon-r13b
Copy link
Contributor Author

charon-r13b commented Dec 23, 2024 •
edited
Loading

生成したソースコードが mvn compile 時にコンパイル対象に含まれるようになるという話をもう少し調べてみたので、結果を追記しました。

cb5a66f

今のOpenAPI Generator Mavenプラグインの使い方だと、sourceFolderを指定すると生成したソースコードをMavenプロジェクトのコンパイル対象に含めるようになります。

これはもともとデフォルトでインターフェースとスケルトンの実装を生成するGenerator向けに設定されているようで、デフォルト設定だとスケルトン実装がコンパイル対象に含まれるようになっています。これはMavenプロジェクトとして操作しています。

https://github.com/OpenAPITools/openapi-generator/blob/v7.10.0/modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java#L1051-L1055

設定項目はそれぞれsourceFolder（デフォルト値 src/gen/java）とimplFolder（デフォルト値 src/main/java）で、NablarchのGeneratorのベースになっているjaxrs-specの基底クラスではsourceFolderのみを使います。このためなにも設定しないとNablarch用のGeneratorではtarget/generated-sources/[プロジェクト名]配下に src/main/javaが生成されないので空振ります。

sourceFolderを明示的に指定することで、sourceFolderがコンパイル対象に含まれるようになります。

https://github.com/OpenAPITools/openapi-generator/blob/v7.10.0/modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java#L1041-L1048

OpenAPI Generatorのデフォルト設定が、なぜ実装側のみをコンパイル対象にしたのかはよくわかりませんが…。

@charon-r13b
Copy link
Contributor Author

charon-r13b commented Jan 10, 2025 •
edited
Loading

Nablarch用のOpenAPI Generatorのリポジトリ移動およびアーティファクト名変更に伴う修正と、バリデーションに関する説明、生成コード例の追加を行いました。

ddc67b4

リポジトリ名およびアーティファクト名の変更に伴い、OpenAPI Generatorの名前から「RESTfulウェブサービス」を外しました（RESTfulウェブサービス用のGeneratorを含むという内容になっています）。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@tishijiri tishijiri tishijiri left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@charon-r13b @tishijiri