REST API Documentation with SpringDoc OpenAPI

Overview

SpringDoc OpenAPI is a powerful tool for documenting REST APIs in Spring Boot. It automatically generates OpenAPI documentation from annotations and can be customized using various annotations provided by the OpenAPI specification.

Key Annotations

• @OpenAPIDefinition: Used for providing metadata about the API, such as title, description, and version.
• @Tag: Groups related operations under a specific name or tag.
• @Operation: Describes individual API operations, such as the HTTP method, summary, and description.
• @ApiResponse: Specifies possible HTTP responses for the API operation.
• @Schema: Used to describe the model or data types of request and response bodies.

Setting up SpringDoc OpenAPI

To start using SpringDoc OpenAPI, you need to add the following dependency in your pom.xml:

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

@OpenAPIDefinition Example

The @OpenAPIDefinition annotation allows you to define API-level information such as the title, description, and version.

    @OpenAPIDefinition(
      info = @Info(
        title = "Employee API",
        version = "1.0",
        description = "API for managing employees"
      )
    )
    @RestController
    @RequestMapping("/api/employees")
    public class EmployeeController {
      // Controller code here
    }
            

Using @Tag for Grouping API Endpoints

The @Tag annotation is used to group related API operations together under a common tag name.

                @Tag(name = "Employee Management", description = "Operations related to employee management")
                @RestController
                @RequestMapping("/api/employees")
                public class EmployeeController {
                // Controller code here
                }
            

@Operation and @ApiResponse for API Documentation

The @Operation annotation provides metadata for an individual API operation. You can define the HTTP method, summary, and detailed description for each operation. The @ApiResponse annotation specifies the possible responses the API can return.

    @Operation(summary = "Get employee by ID", description = "Fetch an employee's details by their unique ID")
    @ApiResponse(responseCode = "200", description = "Successful operation"
                content = @Content(schema = @Schema(implementation = Employee.class)))
    @ApiResponse(responseCode = "404", description = "Employee not found")
    @GetMapping("/{id}")
    public ResponseEntity<Employee> getEmployeeById(@PathVariable Long id) {
      // Method implementation
    }
            

@Schema for Describing Data Models

The @Schema annotation is used to describe the structure of request and response bodies. It can also be used to specify constraints like minimum and maximum values, and required fields.

    public class Employee { 
      @Schema(description = "Unique identifier of the employee", example = "1", required = true) 
      private Long id;
      @Schema(description = "Name of the employee", example = "John Doe") 
      private String name;
      @Schema(description = "Employee's department", example = "HR") 
      private String department;
      // Getters and Setters 
        }
            

Sample API Response

Here is an example of a response from the /api/employees/{id} endpoint:

                { 

                  "id": 1,
                  "name": "John Doe",
                  "department": "HR"
                }
            

Conclusion

SpringDoc OpenAPI simplifies the process of documenting your Spring Boot REST APIs by generating OpenAPI-compliant documentation based on annotations. Using annotations like @OpenAPIDefinition, @Tag, @Operation, @ApiResponse, and @Schema, you can easily create detailed and organized API documentation.