JSONDoc

easily generate docs and playground for your RESTful API

Contacts

Email StackOverflow


With plain Spring MVC annotations

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) {
        // ...
	}

}

Integrated with JSONDoc annotations

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) {
	        // ...
	}

}

Version 1.2.17 | Licensed under MIT License

GitHub Project | Issues