jaxrsを使用して開発された大規模APIのための最良の方法を見つけ出し、サードパーティのために文書化する作業が行われました。このコードは現在、javadocで十分に文書化されています。私の質問は、今までの私の研究に基づいた最良のアプローチを特定し、正しい道を辿ることを確認することです。私は、見るべき入力、コメント、または追加のフレームワークを探しています。これは一般的な使用例であり、他の人も同じような問題を抱えていると確信しています。Java用swaggerを使用した休止エンドポイントの自動生成
我々は要件があります。私たちは、コードを乱雑に注釈の膨大な数を持っていない
- を。
- ネストされたオブジェクトや適切なJSON構造などの戻り値の型をドキュメント化できます。
- ヘッダー、リンク、メタ情報を指定することができます（1.2よりもむしろswagger 2.0が必要です）。
- できるだけ時間とコストを最小限に抑えたいが、質の高い文書を残したい。私は、次の枠組みを検討しているが、それぞれが（このプロジェクトのために）で動作するようにそれらを困難にしていずれかのことを、いくつかの大きな欠点を持っているように見える、または8
JDKと
闊歩JAXRSドックレット：Link
このMavenプラグインは、ビルド時に動作し、既存のJavadocコメントに基づいて合理的な文書を私たちに提供することができます。 However, it does not support Swagger 2.0は、私たちのユースケースに不可欠なレスポンスにヘッダーを記述することに制限を加える可能性があります。これは、swagger mavenプラグインが必要とする@Apiまたは@ApiOperationアノテーションを必要とせずに、残りのサービスを取得することができます。これをswagger 2.0で動作させるためにアップグレードすることは、相当な作業です。
SWAGGERのMavenプラグイン：Link
プラグインは、注釈ではなくコメントに基づいて、ビルド時に闊歩のドキュメントを作成します。これでは、プロジェクト全体を見渡し、@Apiと@ApiOperationで注釈を付ける必要があります。いくつかの注釈は基底クラスのみで取り除かれるかもしれませんが、エンドポイントの説明やタイトルについては注釈内に詳細を追加する必要があります。これらの注釈の多くは重複しているように見えます。たとえば、すでに@Getまたは@Postがありますが、@ApiOperationを追加して、javadocにすでに記述されているパラメータを記述する必要があります。これは時間がかかり、非常に混乱したコードになります。
闊歩コア：Link
闊歩コアは、我々は、既存のjavadocからのコメントを取り除くことができないことを意味し、実行時に動作します。 Swagger Maven Pluginと同じように簡単に拡張できます。リンクやメタ情報を追加するための独自のリーダーやルールを追加することもできます（既存の注釈を使用することもできます）。欠点は、各メソッドの説明がどこかから来る必要があるため、新しいコードを追加するときに忘れられる可能性のある（さらに多くの）注釈に追加する必要があります。
発音する：Link
我々は、.NET上で同様のフレームワークを使用できるようにする必要があり、それはまた（まだ）JDK 8をサポートしていないと発音するが、私たちのために動作しません。
私の結論は、これまで
闊歩jaxrsドックレットは、我々がこれまでにしたいすべてのものをやってに最も近いとなっています。主な問題は、魅力的な2.0の欠如です。一緒に文書化される（異なる言語の）他のプロジェクトが行うように、それに応じてswaggerのバージョンを更新する必要があります。 2番目に良いのはSwagger Mavenプラグインです。これはカスタムランナーの場合と同様にビルド時間なので、何とか既存のjavadocコメントにアクセスし、これらを作成したswaggerに追加することが可能でなければなりません。いくつかのアノテーションはベースクラスにあり、カスタムリーダーを使用してコメントからコメント（例：説明）を引き出します。最後に、既存のjavadocを複製する多くの注釈が必要になるため、swaggerコアは実際に私たちのニーズに対応しません。
swagger 2.0をサポートするためにswaggerドックレットを更新するために必要な時間が不明なので、私はカスタム読者でswagger mavenプラグインに頼りにしています。私の結論が間違っているような、欠けているフレームワークや詳細はありますか？
Springを使用している場合、Springfox（http://springfox.github.io/springfox/docs/current）もオプションです。 – Sampada
ありがとうございます - 残念ながら、それは春ではありませんが、この質問を見て次の人がいるかもしれませんので、とにかくあなたのために投票します。 – ThePerson