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