Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:

>> GET ACCESS NOW

November Discount Launch 2022 – TEMP TOP (NPI)
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:

>> GET ACCESS NOW

1. Overview

In this tutorial, we will briefly look at Swagger's @ApiParam and @ApiModelProperty annotations. Furthermore, we will compare these annotations and identify the correct usage for each.

2. Key Difference

Simply put, @ApiParam and @ApiModelProperty annotations add different metadata to Swagger. The @ApiParam annotation is for the parameters of an API resource request, whereas @ApiModelProperty is for properties of the model.

3. @ApiParam

The @ApiParam annotation is for use solely with the JAX-RS 1.x/2.x parameter annotations like @PathParam, @QueryParam, @HeaderParam, @FormParam, and @BeanParam. Although swagger-core scans these annotations by default, we can use @ApiParam to add more details about the parameters or change the values as they are read from the code.

The @ApiParam annotation helps to specify the name, type, description (value), and example value of the parameter. Moreover, we can specify whether the parameter is required or optional.

Let's look at its usage:

@RequestMapping(
    method = RequestMethod.POST,
    value = "/createUser",
    produces = "application/json; charset=UTF-8")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiOperation(value = "Create user",
  notes = "This method creates a new user")
public User createUser(
  @ApiParam(
    name =  "firstName",
    type = "String",
    value = "First Name of the user",
    example = "Vatsal",
    required = true)
  @RequestParam String firstName) {
 
    User user = new User(firstName);
    return user;
}

Let's look at the Swagger UI representation for our @ApiParam example:

userimage

Now, let's look at @ApiModelProperty.

4. @ApiModelProperty

The @ApiModelProperty annotation allows us to control Swagger-specific definitions such as description (value), name, data type, example values, and allowed values for the model properties.

Also, it offers additional filtering properties in case we want to hide the property in certain scenarios.

Let's add a few model properties to the User's firstName field:

@ApiModelProperty(
  value = "first name of the user",
  name = "firstName",
  dataType = "String",
  example = "Vatsal")
String firstName;

Now, let's take a look at the User Model's specifications in Swagger UI:

usermodel

5. Conclusion

In this quick article, we looked at two Swagger annotations we can use to add metadata for parameters and model properties. Then, we looked at some sample code using those annotations and saw their representations in Swagger UI.

As always, all these code samples are available over on GitHub.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until tomorrow:

>> GET ACCESS NOW

REST footer banner
Comments are closed on this article!