easily generate docs and playground for your RESTful API
JSONDoc will extract as much as possible from Spring's annotations like @Controller, @RestController, @RequestMapping, @PathVariable and so on. No additional JSONDoc annotation is needed to document your rest services. It is still needed to annotate objects' classes with JSONDoc's @ApiObject annotation to document them. If you want to produce a richer documentation, you can annotate your controllers and methods with JSONDoc's annotations, that will integrate Spring's ones. Example:
package org.jsondoc.sample.controller;
@Controller // or @RestController
@RequestMapping(value = "/cities")
public class CityApi {
@RequestMapping(value = "/{name}")
public @ResponseBody City getCityByName(@PathVariable(value = "name") String name) {
// ...
}
}Here is an example on how to use JSONDoc annotations on your Spring MVC controller classes:
package org.jsondoc.sample.controller;
import org.jsondoc.core.annotation.Api;
import org.jsondoc.core.pojo.ApiStage;
import org.jsondoc.core.pojo.ApiVisibility
@Api(name = "city services", description = "Methods for managing cities", group = "Geography", visibility = ApiVisibility.PUBLIC, stage = ApiStage.RC)
@ApiVersion(since = "1.0", until = "2.12")
@ApiAuthNone
@Controller // or @RestController
@RequestMapping(value = "/cities",
public class CityApi {
@ApiMethod
@RequestMapping(value = "/{name}",
method = RequestMethod.GET,
produces = { MediaType.APPLICATION_JSON_VALUE },
consumes = { MediaType.APPLICATION_JSON_VALUE })
public @ApiResponseObject @ResponseBody City getCityByName(@ApiPathParam(description = "The name of the city") @PathVariable(value = "name") String name) {
// ...
}
}