問題タブ [openapi-generator]

私は常に新しい機能 (API の変更) を追加している Java アプリケーションを維持しています。APIを文書化する方法としてOpenAPIを使用する方向に進みたいです。2 つの考え方があります。

1. コードを記述し、いくつかの注釈を使用して OpenAPI 仕様を生成します。
2. OpenAPI を作成し、それを使用してサーバー コードを生成します。

両方ともうまく機能しているように見えますが、サーバー コードは単純にスタブ化されているため、サービスを手動でプラグインする作業が多く必要になります。1回限りのコストとしては問題ないように思えますが、次にインターフェイスを更新するときは、次の2つのオプションしかないように思えます

1. それらをすべて再度生成し、すべての手動配線をやり直します。
2. 以前に生成されたクラスを手動で編集して、新しい仕様ファイルと一致させます (エラーが発生する可能性があります)。

これらのオプションは正しいですか？もしそうなら、コードを使用して api 仕様ファイルを生成することが、実際には唯一の適切な選択であるように思われます。

APIファーストのアプローチを使用しており、サービスのAPIはswagger yamlで定義されています。次に、Openapi ジェネレーターを使用して、マイクロサービスによって実装する必要があるインターフェイスを生成します。また、モデルはスキーマから生成されます。

ここで問題が発生します。REST エンドポイントの 1 つで、Spring-boot によってモデルに解析される XML を使用してから、データベースに保存します。現時点では、次のようなモデルを使用しています。

他のモデルはかなり似ています。Spring-boot はこれを使用して着信 XML を自動的に解析でき、このモデルをデータベースに直接保存して JSON として返すことができるので、私はこれが気に入っています。

Openapi Generator によって生成されたモデルには注釈がないため、XML の解析に使用できず、データベースに保存できません。@Id、@Documentおよびいくつかの@Xml...注釈を追加するようにyamlに指示する方法はありますか?

私がこれをやろうとしている主な理由 (swagger から自動生成されたモデルを使用) は、これがより大きなアーキテクチャであるためです。誰かが yaml の API 定義を変更したり、たとえばマイクロサービスがフィールドを追加したりすると便利です。また、再度ビルドすると、Java クラスを手動で更新しなくてもモデルが更新されます。私が考えたもう 1 つの方法は、Openapi と同じようにモデルを生成し、それを独自のクラスで拡張し、その後何らかの形で注釈を追加することでした...しかし、派生を変更する必要がないように、これを行う方法は考えられません。定義内のフィールドが変更された場合のクラス。

例：

@Xml...これは問題ありませんが、一部のフィールドの注釈が欠落している可能性があります。@JsonProperty("somename")json 命名の場合は問題なく名前が生成されることXML: name/attributeがわかりましたが、yaml でプロパティを使用しても、生成された Java コードに影響を与えないようです (または、これを試してみて、何か間違ったことをしています: Documentation )

私が考えることができる唯一のことは@Override、ゲッター/セッターに属性を付けて注釈を付けることですが、それは、API によって定義されたモデルの派生物を使用するすべてのマイクロサービスに触れなければならないことを意味します。コンテキスト (この場合は XML/mongo) はマイクロサービスごとに大きく異なる可能性があるため、派生クラスを API プロジェクトに移動することはできません。

これに対する良いアプローチに関するアイデアはありますか?

乾杯

- - - 編集 - - -

@XmlAttributeより深く掘り下げた後、ドキュメントに記載されている方法で XML マッピング ( / @XmlElement) アノテーションを swagger yaml に追加し、それをマイクロサービス コードで拡張してデータベースを追加することがおそらく正しいアプローチであると確信しています。注釈。基本的に 2 番目の例と同様に、基本クラスでは XML 注釈が既に swagger codegen によって生成されているという点だけです。ただし、スキーマ/モデルを構築するときに、swagger codegen に XML 注釈を生成させることはまだできていません。

現在、openapi をいじっていて、XML ファイルを使用するエンドポイントを作成しようとしています。しかし、openapi を使用してモデルを作成すると、私が慣れているすべての XML 注釈が欠落しているようです。これは私が使用している openapi.yaml です。

MyRequestスキーマが今問題になっています。name プロパティを XML 属性として宣言していることに注意してください。生成されたクラスは次のようになります。

これは、スプリング ブート ジェネレーターを使用して生成しました。@XmlAttribute名前フィールドの上に注釈が存在することを期待していました。@XmlRootElementまた、クラスのトップになることも期待していました。

何らかの理由で、生成されたコードを現在実行できませんが<MyRequest name="foobar">、エンドポイントに送信すると、そのモデルで解析できないようです。

正しい注釈を生成するために、構成オプションなどを見逃していませんか?

openapi のソースコードを見ると、必要な注釈があります

• クラス ヘッダー テンプレート
• モデル テンプレート (24 行目)