Swagger 3 annotations in Spring Boot

In previous post, we’ve known how to use and configure Swagger 3 in Spring Boot application. This tutorial will give you more examples of Swagger 3 annotations.

You can also apply this tutorial on following Projects:
– Spring Boot 3 Rest API example
– Spring Boot Rest API with H2
– Spring Boot Rest API with MySQL
– Spring Boot Rest API with PostgreSQL
– Spring Boot Rest API with MongoDB
– Spring Boot Rest API with SQL Server
– Spring Boot Rest API with Cassandra
– Spring Boot Rest API with Oracle

More Practice:
– Spring Boot + GraphQL example
– Spring Boot + OpenAPI 3 example
– Spring Boot WebFlux Rest API example
– Spring Boot Security and JWT tutorial with example
– Spring Boot @ControllerAdvice & @ExceptionHandler example
– @RestControllerAdvice example in Spring Boot
– Spring Boot Unit Test for Rest Controller
– Caching: Spring Boot Redis Cache example

Contents

Swagger 3 overview
Swagger 3 annotations
Swagger 2 to Swagger 3 annotations
Add Swagger 3 into Spring Boot
- Spring Boot 3
- Spring Boot 2
Swagger 3 annotations example
Source Code
Conclusion
Further Reading

Swagger 3 overview

OpenAPI Specification sets forth a set of guidelines for API development and documentation, encompassing versioning, schema, document structure, and other critical elements, which contributes to creating reliable and consistent APIs.

Swagger provides a range of tools (Swagger Editor, Swagger UI, Swagger Codegen…) to support the development, testing, and documentation of these APIs. So we can think about Swagger 3 as OpenAPI 3 specification implementation.

Swagger 3 vs OpenAPI 3?

All Swagger tools, which are supported by SmartBear Software, utilize OpenAPI Specification.
But not all OpenAPI tools are Swagger tools. There are many open source and pro tools, which are not related to Swagger, support the OpenAPI 3 Specification.

Swagger 3 annotations

Swagger 3 annotations are already included in springdoc-openapi-ui dependency for Spring Boot 2, or springdoc-openapi-starter-webmvc-ui for Spring Boot 3 with io.swagger.v3.oas.annotations package.

Here are some useful annotations:

@Tag
@Operation
@Parameters and @Parameter
@Schema
@Hidden or @Parameter(hidden = true) or @Operation(hidden = true)
@ApiResponses and @ApiResponse

Swagger 2 to Swagger 3 annotations

Swagger 3 is an updated version of Swagger 2 and has some changes in annotations:

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

Add Swagger 3 into Spring Boot

Spring Boot 3

To use Swagger 3 annotation in Spring Boot 3, you need to add the springdoc-openapi-starter-webmvc-ui dependency to your Maven project’s pom.xml file:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.0.3</version>
</dependency>

Or Gradle project with build.gradle file:

implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.0.3'

Spring Boot 2

With earlier version of Spring Boot, you can use springdoc-openapi-ui dependency in Maven project’s pom.xml file:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.6.15</version>
</dependency>

Or Gradle project with build.gradle file:

implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.15'

Swagger 3 annotations example

Rest API

Assume that we have Spring Boot Application that exposes Rest APIs for a Tutorial application in that:

Each Tutorial has id, title, description, published status.
Apis help to create, retrieve, update, delete Tutorials.
Apis also support custom finder methods such as find by published status or by title.

Methods	Urls	Actions
POST	/api/tutorials	create new Tutorial
GET	/api/tutorials	retrieve all Tutorials
GET	/api/tutorials/:id	retrieve a Tutorial by `:id`
PUT	/api/tutorials/:id	update a Tutorial by `:id`
DELETE	/api/tutorials/:id	delete a Tutorial by `:id`
DELETE	/api/tutorials	delete all Tutorials
GET	/api/tutorials/published	find all published Tutorials
GET	/api/tutorials?title=[keyword]	find all Tutorials which title contains `keyword`

You can find how to implement this Rest API server in one of following tutorials (with Github):
– Spring Boot 3 Rest API example
– Spring Boot Rest API with H2
– Spring Boot Rest API with MySQL
– Spring Boot Rest API with PostgreSQL
– Spring Boot Rest API with MongoDB
– Spring Boot Rest API with SQL Server
– Spring Boot Rest API with Cassandra
– Spring Boot Rest API with Oracle

Let’s use Swagger 3 annotations in our Spring Boot app.

Swagger 3 @Tag annotation

In Swagger 3, the @Tag annotation is used to provide additional information about tags in the Swagger documentation. Tags are used to group API operations together and provide a way to categorize and organize them in a meaningful way.

In following example, the @Tag annotation is used to define a tag called “Tutorial” with description: “Tutorial management APIs”. The tag is then applied to the TutorialController class.

@Tag(name = "Tutorial", description = "Tutorial management APIs")
@RestController
@RequestMapping("/api")
public class TutorialController {

  @PostMapping("/tutorials")
  public ResponseEntity<Tutorial> createTutorial(@RequestBody Tutorial tutorial) {

  }

  @GetMapping("/tutorials")
  public ResponseEntity<List<Tutorial>> getAllTutorials(@RequestParam(required = false) String title) {

  }

  @GetMapping("/tutorials/{id}")
  public ResponseEntity<Tutorial> getTutorialById(@PathVariable("id") long id) {

  }

  @PutMapping("/tutorials/{id}")
  public ResponseEntity<Tutorial> updateTutorial(@PathVariable("id") long id, @RequestBody Tutorial tutorial) {

  }

  @DeleteMapping("/tutorials/{id}")
  public ResponseEntity<HttpStatus> deleteTutorial(@PathVariable("id") long id) {
    
  }

  @DeleteMapping("/tutorials")
  public ResponseEntity<HttpStatus> deleteAllTutorials() {
    
  }

  @GetMapping("/tutorials/published")
  public ResponseEntity<List<Tutorial>> findByPublished() {
    
  }
}

When the Swagger documentation is generated, the @Tag annotation will group all of the operations that belong to the “Tutorial” tag together in the documentation. This makes it easy for users to find all of the operations that are related to tutorials.

The @Tag annotation can be added to a method inside a Controller to provide a name and description for the tag. For example:

public class TutorialController {

  @Tag(name = "tutorials", description = "Tutorial APIs")
  @PostMapping("/tutorials")
  public ResponseEntity<Tutorial> createTutorial(@RequestBody Tutorial tutorial) {

  }
}

Swagger 3 @Operation annotation

In Swagger 3, the @Operation annotation is used to provide metadata for a single API operation.

Here’s an example of how the @Operation annotation can be used in Spring Boot:

public class TutorialController {

  @Operation(
      summary = "Retrieve a Tutorial by Id",
      description = "Get a Tutorial object by specifying its id. The response is Tutorial object with id, title, description and published status.",
      tags = { "tutorials", "get" })
  @GetMapping("/tutorials/{id}")
  public ResponseEntity<Tutorial> getTutorialById(@PathVariable("id") long id) {

  }
}

In this example, the @Operation annotation provides a summary, description and set tags for the getTutorialById method operation.

Swagger 3 @ApiResponses and @ApiResponse annotation

In Swagger 3, the @ApiResponses annotation can be added to an API operation method to provide a list of possible responses for that operation. Each response is specified using an @ApiResponse annotation.

The @ApiResponse annotation specifies the HTTP status code, description, and content of a response. The content is described using the @Content annotation, which includes the media type and schema of the response body.

public class TutorialController {

  @ApiResponses({
    @ApiResponse(responseCode = "200", content = { @Content(schema = @Schema(implementation = Tutorial.class), mediaType = "application/json") }),
    @ApiResponse(responseCode = "404", description = "The Tutorial with given Id was not found.", content = { @Content(schema = @Schema()) })
  })
  @GetMapping("/tutorials/{id}")
  public ResponseEntity<Tutorial> getTutorialById(@PathVariable("id") long id) {

  }
}

In this example, the @ApiResponse annotation is used to define two possible responses for the getTutorialById method. The first response (responseCode = "200") indicates a successful response with a JSON representation of the Tutorial object in the response body. The second response (responseCode = "404") indicates that the requested Tutorial Id was not found.

Swagger 3 @Parameter annotation

The @Parameter annotation in Swagger 3 is used to describe a parameter for an operation in an OpenAPI / Swagger document. For example:

public class TutorialController {
  
  @GetMapping("/tutorials")
  public ResponseEntity<Map<String, Object>> getAllTutorials(
      @Parameter(description = "Search Tutorials by title") @RequestParam(required = false) String title,
      @Parameter(description = "Page number, starting from 0", required = true) @RequestParam(defaultValue = "0") int page,
      @Parameter(description = "Number of items per page", required = true) @RequestParam(defaultValue = "3") int size) {
    
  }
}

In the example, the @Parameter annotation describes each of the parameters (title, page, and size) of the getAllTutorials method. The description attribute provides a brief description of each parameter, and the required attribute is set to true to indicate that the parameter is mandatory.

Note that the @Parameter annotation can be used in conjunction with other annotations, such as @RequestParam, @PathVariable, or @RequestBody, depending on the type of parameter being described.

Here is the result:

Or you can use @Parameters annotation to define multiple input parameters for an operation.

public class TutorialController {

  @Parameters({
    @Parameter(name = "title", description = "Search Tutorials by title"),
    @Parameter(name = "page", description = "Page number, starting from 0", required = true),
    @Parameter(name = "size", description = "Number of items per page", required = true)
  })
  @GetMapping("/tutorials")
  public ResponseEntity<Map<String, Object>> getAllTutorials(
      @RequestParam(required = false) String title,
      @RequestParam(defaultValue = "0") int page,
      @RequestParam(defaultValue = "3") int size) {
    
    return null;
  }
}

Swagger 3 @Schema annotation

In Swagger 3, the @Schema annotation is used in to provide additional information about the schema of a model or parameter in your API.

Let’s use @Schema annotation to define a schema for a Tutorial object.

@Schema(description = "Tutorial Model Information")
public class Tutorial {

  @Schema(accessMode = Schema.AccessMode.READ_ONLY, description = "Tutorial Id", example = "123")
  private long id = 0;

  @Schema(description = "Tutorial's title", example = "Swagger Tutorial")
  private String title;

  @Schema(description = "Tutorial's description", example = "Document REST API with Swagger 3")
  private String description;

  @Schema(description = "Tutorial's status (published or not)", example = "true")
  private boolean published;

  public Tutorial() {

  }

  // getters and setters
}

In the example above, the @Schema annotation provides additional information about the Tutorial class and its fields. The description attribute provides a brief description of what each field represents, while the example attribute provides a sample value for each field.

We use accessMode = Schema.AccessMode.READ_ONLY in the id property. This will mark the id property as readOnly: true in the generated OpenAPI definition.

The Schema with its example value is changed now.

Source Code

The complete source code for this tutorial is on Github.

Conclusion

Today we’ve known how to use Swagger 3 annotations in Spring Boot example for OpenAPI 3 Specification. We also make configuration for API description and response example.

You can also apply the code easily on following Projects:
– Spring Boot 3 Rest API example
– Spring Boot Rest API with H2
– Spring Boot Rest API with MySQL
– Spring Boot Rest API with PostgreSQL
– Spring Boot Rest API with MongoDB
– Spring Boot Rest API with SQL Server
– Spring Boot Rest API with Cassandra
– Spring Boot Rest API with Oracle

Or cache the response with Redis: Spring Boot Redis Cache example

Happy Learning! See you again.