サーブレットに裏打ちされたAPIのドキュメントを生成する良い方法はありますか？

Question

javaサーブレットのコレクションの外部ドキュメントを生成するための優れたツールや戦略について知っている人はいますか？もちろん私のお気に入りのリッチテキストエディタを使って独立した文書を作成することもできます。しかし、ドキュメンテーションがソースコード内にあれば、維持される可能性が高くなります。残念ながら、問題は少し構造化されていません。各サーブレットはJavaクラスですが、それが正式な構造の終わりです。サーブレットのdoGetメソッドの中では、URLエンコードされたパラメータのセットを完全に非構造化された方法で消費し、何らかの出力を生成します（たとえば、WebページやJSONオブジェクトなど）。

Javadocはコード自体を文書化することはまともですが、私のサービスのクライアントが見たAPIを文書化したいと思います。

javadocスタイルでは、ドキュメントをクラスに配置して、パラメータを表すdoGetメソッドのローカル変数を設定するためのアノテーションを定義することができます。しかし、私はまだ特殊な処理が必要です。javadocがデフォルトで生成するものは望んでいません。

（はい、私は心強い答えを持っていないこの他の質問What's the best way to generate a REST API's documentation?を、見てきましたが、私は、私は少し質問を言い換えてみたいと思った。）

Answer 1

私はあなたがプロパティのカップルを追加する必要がありますでしょうねサーブレットに - parametersプロパティとresponse_detailsプロパティ（またはそれに類するもの）を追加します。そしてサーブレット署名の一部としてそれらを必要とします。それらは、そのサーブレットの入力と出力を記述する一般的なテキスト形式（Markdown、ReST？）の文字列を含むことができます。

サーブレットクラスをイントロスペクションし、使用するマークアップ形式の適切な既存のプロセッサと、viola、docsで結果の文字列を実行できます。

たとえば、parametersがMap<String,String>などであることが必要な場合など、これらのプロパティに実際に必要なものに構造体を追加できます。それはすべてあなた次第です。