OpenAPI

@OpenApiDefinition

The @OpenAPIDefinition annotation is used to annotate a Java class, typically at the top level of your application or API, to provide metadata and configuration for generating the OpenAPI specification

import io.swagger.v3.oas.annotations.ExternalDocumentation;  
import io.swagger.v3.oas.annotations.OpenAPIDefinition;  
import io.swagger.v3.oas.annotations.info.Contact;  
import io.swagger.v3.oas.annotations.info.Info;  
import io.swagger.v3.oas.annotations.info.License;  
import org.springframework.boot.SpringApplication;  
import org.springframework.boot.autoconfigure.SpringBootApplication;  
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;  
  
@SpringBootApplication  
@EnableJpaAuditing(auditorAwareRef = "auditAwareImpl")  
@OpenAPIDefinition(  
       info = @Info(  
             title = "Accounts microservice REST API Documentation",  
             description = "microservice REST API Documentation",  
             version = "v1",  
             contact = @Contact(  
                   name = "elias",  
                   email = "elias@mail.com",  
                   url = "https://www.eliasmanj.com"  
             ),  
             license = @License(  
                   name = "Apache 2.0",  
                   url = "https://www.eiasmanj.com"  
             )  
       ),  
       externalDocs = @ExternalDocumentation(  
             description =  "microservice REST API Documentation",  
             url = "https://www.eazybytes.com/swagger-ui.html"  
       )  
)  
public class AccountsApplication {  
  
    public static void main(String[] args) {  
       SpringApplication.run(AccountsApplication.class, args);  
    }  
  
}

info: This attribute allows you to specify metadata about the API, such as the title, version, description, and other information.

externalDocs: You can use this attribute to provide external documentation for your API. It includes a URL and a description.

@Tag

The @Tag annotation is used to categorize and organize API operations (endpoints) into tags or groups in the generated OpenAPI specification

@Tag(  
        name = "CRUD REST APIs for Accounts",  
        description = "CRUD REST APIs in to CREATE, UPDATE, FETCH AND DELETE account details"  
)  
@RestController  
@RequestMapping(path="/api", produces = {MediaType.APPLICATION_JSON_VALUE})  
@AllArgsConstructor  
@Validated  
public class AccountsController {
	... 
}

@Operation

The @Operation annotation in Java, within the context of OpenAPI and Swagger, is used to provide additional information and metadata about a specific API operation (or endpoint) in a RESTful API. This annotation is applied to the methods that represent the individual operations in a Java class.

Here's a breakdown of some key attributes of the @Operation annotation:

summary: This attribute provides a short summary or description of the operation. It is typically a concise, one-sentence description of what the operation does.
description: This attribute allows for a more detailed description of the operation. It can include additional information about the purpose, behavior, and usage of the operation.

@Operation(summary = "Get user by ID", description = "Returns a single user by ID")
public User getUserById(@Parameter(description = "ID of the user") Long userId) {
    // Implementation logic
}

@ApiResponse

@ApiResponse is typically used to document the possible responses that an API endpoint can produce. This annotation is often used in conjunction with the @ApiOperation annotation to provide comprehensive documentation for your API

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@RestController
@OpenAPIDefinition(value = "Example API", description = "Sample API for demonstration purposes")
public class ExampleController {

    @GetMapping("/example")
    @Operation(value = "Get example data", notes = "This endpoint returns some example data.")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully retrieved data"),
            @ApiResponse(code = 404, message = "Data not found"),
            @ApiResponse(code = 500, message = "Internal server error")
    })
    public ResponseEntity<String> getExampleData() {
        // Implementation of the endpoint logic
        // ...

        // Return a ResponseEntity with appropriate status and data
        return new ResponseEntity<>("Example data", HttpStatus.OK);
    }
}

@Schema

The @Schema annotation is used to provide additional information about the data model (schema) of a particular object, parameter, or response. It allows you to specify details such as the data type, format, description, and other properties of the schema.

@Schema(  
        name = "Accounts",  
        description = "Schema to hold Account information"  
)  
public class AccountsDto {  
  
    @NotEmpty(message = "AccountNumber can not be a null or empty")  
    @Pattern(regexp="(^$|[0-9]{10})",message = "Account must be 10 digits")  
    @Schema(  
            description = "Account Number ofaccount", example = "3454433243"  
    )  
    private Long accountNumber;  
  
    @NotEmpty(message = "AccountType can not be a null or empty")  
    @Schema(  
            description = "Account type of account", example = "Savings"  
    )  
    private String accountType;  
  
    @NotEmpty(message = "BranchAddress can not be a null or empty")  
    @Schema(  
            description = "branch address", example = "123 NewYork"  
    )  
    private String branchAddress;  
}