This spring boot v3 project explain the usage of openapi documentation (Swagger v3)
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")
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.1.0</version>
</dependency>
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. The @Tag annotation can be added to a method inside a Controller to provide a name and description for the tag.
@Tag(name = "Customer", description = "Customer management APIs")
In Swagger 3, the @Operation annotation is used to provide metadata for a single API operation.
@Operation(
summary = "Retrieve a customer by Id",
description = "Get a customer object by specifying its id.",
tags = { "customerById", "GET"})
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.
@ApiResponses({
@ApiResponse(responseCode = "200", content = { @Content(schema = @Schema(implementation = CustomerDTO.class), mediaType = MediaType.APPLICATION_JSON_VALUE) }),
@ApiResponse(responseCode = "404", content = { @Content(schema = @Schema(description = "No customer found")) }),
@ApiResponse(responseCode = "500", content = { @Content(schema = @Schema(description = "Server error")) }) })
The @Parameter annotation in Swagger 3 is used to describe a parameter for an operation in an OpenAPI / Swagger document.
@GetMapping("/v1/customer")
public ResponseEntity<?> findCustomerBySurname(@Parameter(explode = Explode.TRUE, name = "surname", in = ParameterIn.QUERY, description = "Customer surname", style = ParameterStyle.FORM, schema = @Schema(type = "string", defaultValue = "available", allowableValues = { "Koli", "Kawali", "Joshi" }))
@RequestParam String surname) {
}
or
@GetMapping("/v1/customer/{id}")
public ResponseEntity<?> customerById(
@Parameter(description = "Customer id", required = true) @PathVariable Long id) {
}
Or you can use @Parameters annotation to define multiple input parameters for an operation.
@Parameters({
@Parameter(name = "id", description = "customer id to search and update", required = true),
@Parameter(name = "CustomerDTO", description = "Customer details to update") })
@PutMapping("/v1/customer/{id}")
public ResponseEntity<?> updateCustomer(@PathVariable Long id, @Valid @RequestBody CustomerDTO customerDTO) {
}
In Swagger 3, the @Schema annotation is used in to provide additional information about the schema of a model or parameter in your API.
@Schema(description = "Customer dto information")
public class CustomerDTO {
@Schema(accessMode = Schema.AccessMode.READ_ONLY, description = "customer id", example = "123133")
@JsonProperty("id")
private Long id;
@Schema(description = "This field describe the customer's name", example = "Rajesh")
@NotBlank(message = "First name shouldn't be null or empty")
@JsonProperty("firstName")
private String firstName;
@Schema(description = "This field describe the customer's surname", example = "Kawali")
@NotNull(message = "Surname shouldn't be null")
@NotEmpty(message = "Surname shouldn't be empty")
@JsonProperty("surname")
private String surname;
}