The Swagger UI also provides annotations to further customize your documentation.

Listed here is some of the ;documentation to retrieve the todos service:

    "/users/{name}/todos": {
      "get": {
      "tags": [
             "todo-controller"
             ],
      "summary": "retrieveTodos",
      "operationId": "retrieveTodosUsingGET",
      "consumes": [
               "application/json"
               ],
      "produces": [
                "*/*"
               ],

As you can see, the documentation generated is very raw. There are a number of things we can improve in the documentation to describe the services better. Here are a couple of examples:

• Provide a better summary
• Add application/JSON to produces

Swagger provides annotations we can add to our RESTful services in order to customize the documentation. ;Let's add a few annotations to the controller in order to improve the documentation:

    @ApiOperation(
      value = "Retrieve all todos for a user by passing in his name", 
      notes = "A list of matching todos is returned. Current pagination   
      is not supported.",
      response = Todo.class, 
      responseContainer = "List", 
      produces = "application/json")
      @GetMapping("/users/{name}/todos")
      public List<Todo> retrieveTodos(@PathVariable String name) {
        return todoService.retrieveTodos(name);
     }

A few important points to note are as follows:

• @ApiOperation(value = "Retrieve all todos for a user by passing in his name"): Produced in the documentation as a summary of the service
• notes = "A list of matching todos is returned. Current pagination is not supported.": Produced in the documentation as a description of the service
• produces = "application/json”: Customizes the produces section of the service documentation

Here is an extract of the documentation after the update:

    get": {
         "tags": [
                   "todo-controller"
                 ],
         "summary": "Retrieve all todos for a user by passing in his 
          name",
         "description": "A list of matching todos is returned. Current 
          pagination is not supported.",
         "operationId": "retrieveTodosUsingGET",
         "consumes": [
                     "application/json"
                   ],
         "produces": [
                     "application/json",
                     "*/*"
                   ],

Swagger provides a lot of other annotations to customize the documentation. Listed here are some of the important annotations:

• @Api: Marks a class as a Swagger resource
• @ApiModel: Provides additional information about Swagger models
• @ApiModelProperty: Adds and manipulates the data of a model property
• @ApiOperation: Describes an operation or an HTTP method against a specific path
• @ApiParam: Adds additional metadata for operation parameters
• @ApiResponse: Describes an example response of an operation
• @ApiResponses: A wrapper to allow a list of multiple ApiResponse objects.
• @Authorization: Declares an authorization scheme to be used on a resource or an operation
• @AuthorizationScope: Describes an OAuth 2 authorization scope
• @ResponseHeader: Represents a header that can be provided as part of the response

Swagger provides a few Swagger definition annotations that can be ;used to customize high-level information about a group of services--contacts, licensing, and other general information. Listed here are some of the important ones:

• @SwaggerDefinition: Definition-level properties to be added to the generated Swagger definition
• @Info: General metadata for a Swagger definition
• @Contact: ;Properties to describe the person to be contacted for a Swagger definition
• @License: Properties to describe the license for a Swagger definition