Restful JSON API 文件產生器整理

寫程式最痛苦的就是寫文件，更痛苦的就一旦程式或介面有修改，也要立即找到相對應的文件修改，也就是這樣才會有文件產生器的誕生，對於一般Java 程式最方變得當然是使用java doc 來產生文件。

但是只要是一談到跨系統跨語言的整合就沒有這麼簡單了，舉例來說 Web service，常見的Web Service 有兩種，一種是XML based 的 SOAP 本身就有一套嚴謹的文件產生規則，所以問題到不大，但是另一種 RESTful Service  就不是這樣了，因為它通常使用JSON的格式在交換訊息，而JSON又是一種很隨性鬆散的結構，這時候如果沒有專門為了 RESTful API的文件產生器那就會很痛苦了....

為了減輕這方面的痛苦，所以特別去找了目前市面上專門為了Java Solution的RESTful service 文件產生器。

不過絕大部分都是針對springmvc 去設計的.....

SpringDoclet

SpringDoclet is a Javadoc doclet that generates documentation on Spring Framwork artifacts in a project. The detection of Spring artifacts is based on the presence of Spring annotations on Java classes and methods.

RESTdoclet

IG Group’s RESTdoclet  is a Maven Doclet plugin for generating REST service documentation from Spring 3 REST implemented services. (必須使用 Spring 3 REST annotations)

Wsdoc

WsDoc is a documentation generator for Spring MVC REST services. Multi modules/war and unified report.

Swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.e overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync. With Swagger, deploying managing, and using powerful APIs has never been easier. swagger-springmvc

JsonDoc

JSONDoc  has a set of completely MVC framework agnostic annotations


雖然知道使用Spring mvc 在java solution 佔大宗，但難道不是使用Spring mvc 開發就不行嘛!? 我想用Jersey 或是 resteasy呢？

後來我找到了Enunciate 它支援標準JAX-WS和 JAX-RS的 annotation，所以不一定要綁定在Spring mvc上 (不過他也有支援)，不過他產生的介面算是裡面比較醜的...Orz..

Enunciate

Enunciate is an engine for dramatically enhancing your Java Web service API. (@javax.ws.rs.Path) It’s simple. You develop your Web service API using standard Java technologies and attach Enunciate to your build process. Suddenly, your Web service API is boasting some pretty impressive features:
- Full HTML documentation of your services, scraped from your JavaDocs.
- Client-side libraries (e.g. Java, .NET, iPhone, Ruby, Flex, AJAX, GWT, etc.) for developers who want to interface with your API.
- Interface Definition Documents (e.g. WSDL, XML-Schema, etc.)