swaggerAs soon as you build an API including a few operations, you will realize that is hard to maintain code and documentation in sync. Therefore you can use a tool like Swagger. It can generate easly a high quality documentation for you.

Swagger is both a specification and a framework implementation. The strength of Swagger is its hability to keep in sync the code and the documentation. Once you integrate Swagger with your server app, it will generate a live RESTful documentation which will let you navigate and test without coding a single line.

How to integrate your Spring Boot Application with Swagger

First step: Enabling Swagger

Including this annotation in a configuration class

@EnableSwagger2

Second step: provide general api information

This is an example

@Bean
public Docket newsApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.description(" is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
.version("1.0.0")
.title("Swagger Petstore")
.termsOfServiceUrl("http://swagger.io/terms/")
.contact(
new Contact(null, null, "apiteam@swagger.io")
)
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build())
.host("localhost:8080")
.tags(
new Tag("name", "pet"),
new Tag("description", "Everything about your Pets")
)
.select().paths(regex("/.*"))
.build();
}

Third step: include annotations in your api

There are a bunch of annotations that can be used but the most important are:

@Api
Marks a class as a Swagger resource
@ApiOperation
Describes an operation or typically a HTTP method against a specific path.
@ApiResponses
A list of multiple ApiResponses
@Controller
@RequestMapping(value = "/pet", produces = {APPLICATION_JSON_VALUE})
@Api(value = "/pet", description = "the pet API")
public class PetApi {
@ApiOperation(value = "Finds Pets by status", notes = "Multiple status values can be provided with comma seperated strings", response = Pet.class, responseContainer = "List")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "successful operation"),
@ApiResponse(code = 400, message = "Invalid status value") })
@RequestMapping(value = "/findByStatus", method = GET)
public ResponseEntity<List<Pet>> findPetsByStatus(
@ApiParam(value = "Status values that need to be considered for filter", defaultValue = "available")
@RequestParam(value = "status", required = false, defaultValue="available") List<String> status
) throws NotFoundException {
// do some magic!
return new ResponseEntity<List<Pet>>(HttpStatus.OK);
}
}

Browsing the live api-doc

Enter this page
http://localhost:8080//swagger-ui.html