[Java] Self-Documented Services Using JAX-RS Analyzer

原文はこちら。
https://blogs.oracle.com/theaquarium/entry/self_documented_services_using_jax

---

SOAPで最もありがたかったのは、Javaのように、強く型付けされているというところです。つまり、WSDLを見るとサービスが何をするのか理解することができます。同様に、生成するクライアントやGUI可視化ツール、正確なドキュメントを含む、SOAPサービスをツールが簡単に読み、使うことができます。WADLはこうした欠点を克服するため、RESTの世界で考案されましたが、不幸にも、WADLはあまりサポートされず、使われていません。全くの未知のユーザーを含む、外部のユーザーが利用するRESTサービスを記述している場合、これは非常に大きな問題です。これまでこの問題に対する回答は手作業でRESTサービスのドキュメントを作成するというもので、非常に面倒で間違いが発生しやすく、しかも最新情報に追随できないものでした（因みに、JAX-RSの参照実装であるJerseyはWADLをサポートしていることはご存知と思います）。
しかしながら、JAX-RS開発者にとって、JAX-RS Analyzerというお助けツールがあります。JAX-RS Analyzerはシンプルですが非常に有用なオープンソースのJAX-RSプラグインで、Sebastian Daschnerが作成しました。このツールはJAX-RSアノテーションやメタデータを自動的に読みとり、プレーンテキスト、AsciiDoc、もしくはSwaggerの形式でドキュメントを作成します。Swaggerオプションは特に魅力的です。Swaggerは現段階においてRESTにおけるWSDLやUDDIのギャップを埋めるものとして最も近いものです。
JAX-RS Analyzerについてあまりご存知でないようでしたら、是非Sam Sepassiのすばらしいエントリをご一読ください。REST APIのドキュメント作成に掛けるうんざりするほどの時間を節約することができるようになるでしょう。

REST API Documentation Using JAXRS-ANALYZER
https://dzone.com/articles/rest-api-documentation-using-jaxrs-analyzer

（訳注）
簡単なJAX-RSサービスで試してみました。。。