Home > Spring > Spring Boot > How to document Controller and Model class using Swagger2 in Spring Boot REST project

How to document Controller and Model class using Swagger2 in Spring Boot REST project

In our article Integrate Swagger2 with Spring Boot REST API, we learned to integrate Swagger2 in our Spring Boot REST application. Here in this article, we will learn how to document the Controller and Model class of our Spring Boot project using annotations provided by Springfox Swagger 2.

Controller Class Documentation

To document our controller class we will use @Api, @ApiOperation, and @ApiResponses annotation. @Api annotation is used to describe the Controller class, @ApiOperation is used to describe the methods or APIs of the controller class, and @ApiResponses annotation is used to describe the API response structure error code and error message. The sample can be seen below. Here we have a ProductController class with CRUD operation’s API.

@RestController
@RequestMapping("/product")
@Api(tags={"Online Store Controller"}, description="Operations pertaining to products in Online Store")
public class ProductController {
    
    @Autowired
    private ProductService productService;

    @ApiOperation(value = "Search a product with an ID",response = Product.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully retrieved the product"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
    }
    )
    @GetMapping(path = "/get-by-id/{id}")
    public Product getById(@PathVariable Integer id, Model model){
        Product product = productService.getProductById(id);
        return product;
    }

    @ApiOperation(value = "Add a product")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully added a Product"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
    }
    )
    @PostMapping(path = "/create")
    public ResponseEntity createProduct(@RequestBody Product product){
        productService.saveProduct(product);
        return new ResponseEntity("Product saved successfully", HttpStatus.OK);
    }

    @ApiOperation(value = "Update a product")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully updated a product"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
    }
    )
    @PutMapping(path = "/update/{id}")
    public ResponseEntity updateProduct(@PathVariable Integer id, @RequestBody Product product){
        Product product = productService.getProductById(id);
        product.setDescription(product.getDescription());
        product.setImageUrl(product.getImageUrl());
        product.setPrice(product.getPrice());
        productService.saveProduct(product);
        return new ResponseEntity("Product updated successfully", HttpStatus.OK);
    }

    @ApiOperation(value = "Delete a product")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully deleted a product"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
    }
    )
    @DeleteMapping(path = "/delete/{id}")
    public ResponseEntity delete(@PathVariable Integer id){
        productService.deleteProduct(id);
        return new ResponseEntity("Product deleted successfully", HttpStatus.OK);
    }
}

Model Class Documentation

To describe a model class @ApiModelProperty Swagger2 annotation is used. The sample can be seen below. Here we will describe the Product model class which we have used in the above ProductController class.

@Entity
public class Product {

	@Id
    @GeneratedValue(strategy = GenerationType.AUTO)
	@ApiModelProperty(notes = "Product Id")
    private Long id;

    @ApiModelProperty(notes = "The product image URL")
    private String imageUrl;

    @ApiModelProperty(notes = "The description of the product")
    private String description;

    @ApiModelProperty(notes = "The price of the product")
    private BigDecimal price;

    ...
}

More Tutorials on Swagger –

Integrate Swagger2 with Spring Boot REST API

Hide an End-points from Swagger Documentation in Spring Boot REST API

How to Disabled Swagger-UI in Production in Spring Boot Project