easily generate docs and playground for your RESTful API
JSONDoc is framework agnostic, meaning that you can use it with your favourite MVC framework. In this case you should only include jsondoc-core
<dependency>
<groupId>org.jsondoc</groupId>
<artifactId>jsondoc-core</artifactId>
<version>1.2.23</version>
</dependency>DefaultJSONDocScanner class (implementation of JSONDocScanner interface) to generate an object of kind JSONDoc that can be later marshalled in JSON with your favourite marshaller.
Here is the code of a Spring MVC controller that returns the JSON containing the documentation (using a different implementation of JSONDocScanner) maybe you will find it useful:
package org.jsondoc.springmvc.controller;
import java.util.List;
import org.jsondoc.core.pojo.JSONDoc;
import org.jsondoc.core.pojo.JSONDoc.MethodDisplay;
import org.jsondoc.core.scanner.JSONDocScanner;
import org.jsondoc.springmvc.scanner.SpringJSONDocScanner;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
public class JSONDocController {
private String version;
private String basePath;
private List<String> packages;
private JSONDocScanner jsondocScanner;
private boolean playgroundEnabled = true;
private MethodDisplay displayMethodAs = MethodDisplay.URI;
public final static String JSONDOC_DEFAULT_PATH = "/jsondoc";
public JSONDocController(String version, String basePath, List<String> packages) {
this.version = version;
this.basePath = basePath;
this.packages = packages;
this.jsondocScanner = new Spring3JSONDocScanner();
}
@RequestMapping(value = JSONDocController.JSONDOC_DEFAULT_PATH, method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
public @ResponseBody JSONDoc getJSONDoc() {
return jsondocScanner.getJSONDoc(version, basePath, packages, playgroundEnabled, displayMethodAs);
}
public boolean isPlaygroundEnabled() {
return playgroundEnabled;
}
public void setPlaygroundEnabled(boolean playgroundEnabled) {
this.playgroundEnabled = playgroundEnabled;
}
public MethodDisplay getDisplayMethodAs() {
return displayMethodAs;
}
public void setDisplayMethodAs(MethodDisplay displayMethodAs) {
this.displayMethodAs = displayMethodAs;
}
}See Configuration for more information about getJSONDoc arguments.
You can include the jsondoc-ui project in your web application. This provides an interface to browse the generated documentation and a playground to test methods. It is built on Twitter Bootstrap and can be easily customized for you needs. To do this you need to get the jsondoc-ui jar, extract it and copy css, js, font, jsondoc-ui.html to your project's webapp folder. Check out the live demo here or the sample applications code. Here is the dependency to the jsondoc-ui:
<dependency>
<groupId>org.jsondoc</groupId>
<artifactId>jsondoc-ui</artifactId>
<version>1.2.23</version>
</dependency>If you are not satisfied with the standard interface, you can use the generated JSON documentation in a fully customized interface!