Swagger Annotations | Generated by AI

Home PDF

To use the swagger-annotations package in your Java project, particularly for documenting a REST API built with Spring Boot, follow these steps. This guide assumes you are using Swagger 2.0, which is commonly integrated with the springfox library. The swagger-annotations package provides annotations to add metadata to your API endpoints, enabling automatic generation of API documentation.

Step 1: Add the Required Dependencies

You need to include the swagger-annotations package and a Swagger integration library (e.g., springfox) in your project. If you’re using Maven, add the following dependencies to your pom.xml:

<!-- Swagger Annotations -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.6.2</version>
</dependency>

<!-- Springfox Swagger 2 for Swagger Integration -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- Springfox Swagger UI for Interactive Documentation -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Note: Check for the latest versions on Maven Repository as these versions (1.6.2 for swagger-annotations and 2.9.2 for springfox) may have updates.

Step 2: Configure Swagger in Your Application

To enable Swagger and allow it to scan your API for annotations, create a configuration class with a Docket bean. Add this to your Spring Boot application:

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any()) // Scan all controllers
                .paths(PathSelectors.any())          // Include all paths
                .build();
    }
}

Step 3: Use Swagger Annotations in Your Code

The swagger-annotations package provides annotations to describe your API. Apply these to your controller classes, methods, parameters, and models. Below are common annotations with examples:

Annotating a Controller

Use @Api to describe the controller:

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "User Controller", description = "Operations pertaining to users")
@RestController
@RequestMapping("/users")
public class UserController {
    // Methods go here
}

Annotating API Operations

Use @ApiOperation to describe individual endpoints:

import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

@ApiOperation(value = "Get a user by ID", response = User.class)
@GetMapping("/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Implementation
    return ResponseEntity.ok(new User(id, "John Doe"));
}

Describing Parameters

Use @ApiParam for method parameters:

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

@ApiOperation(value = "Create a new user")
@PostMapping
public ResponseEntity<User> createUser(
        @ApiParam(value = "User object to be created", required = true) 
        @RequestBody User user) {
    // Implementation
    return ResponseEntity.ok(user);
}

Specifying Responses

Use @ApiResponses and @ApiResponse to document possible HTTP responses:

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.ApiResponse;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.PathVariable;

@ApiOperation(value = "Delete a user")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "User deleted successfully"),
    @ApiResponse(code = 404, message = "User not found")
})
@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    // Implementation
    return ResponseEntity.ok().build();
}

Describing Models

For data transfer objects (DTOs), use @ApiModel and @ApiModelProperty:

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "User data transfer object")
public class User {
    @ApiModelProperty(notes = "The user's unique identifier", example = "1")
    private Long id;

    @ApiModelProperty(notes = "The user's name", example = "John Doe")
    private String name;

    // Getters and setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public User(Long id, String name) {
        this.id = id;
        this.name = name;
    }
}

Step 4: Run and Access the Documentation

  1. Start your Spring Boot application.
  2. Open a browser and navigate to:
    http://localhost:8080/swagger-ui.html
    This URL displays the Swagger UI, an interactive interface showing your API documentation based on the annotations.

Summary of How to Use swagger-annotations

  1. Add Dependencies: Include swagger-annotations and springfox in your pom.xml.
  2. Configure Swagger: Set up a Docket bean to enable Swagger scanning.
  3. Annotate Your Code:
    • @Api for controllers.
    • @ApiOperation for methods.
    • @ApiParam for parameters.
    • @ApiResponses and @ApiResponse for response details.
    • @ApiModel and @ApiModelProperty for DTOs.
  4. View Documentation: Access the Swagger UI at /swagger-ui.html.

Additional Notes

By following these steps, you can effectively use the swagger-annotations package to document your REST API, making it easier for developers and consumers to understand and interact with your endpoints.

Back 2025.03.04 Donate