探 SpringDoc OpenAPI 常用註解

@OpenAPIDefinition 和 Info 這些註解聲明 API 資訊：標題、版本、許可證、安全性、伺服器、標籤、安全性和 externalDocs

java 复制代码

@OpenAPIDefinition(
    info = @Info(
        title = "Accounts microservice REST API",
        description = "Accounts microservice REST API",
        version = "v1.0",
        contact = @Contact(
            name = "Danny Yu",
            email = "[EMAIL_ADDRESS]"
        ),
        license = @License(
            name = "Apache 2.0",
            url = ""
        )
    ),
    externalDocs = @ExternalDocumentation(
        description = "Accounts microservice REST API documentation",
        url = "https://www.demo.com/swagger-ui.html"
    )
)public class AccountsApplication {
    public static void main(String[] args) {
        SpringApplication.run(AccountsApplication.class, args);
    }
}

@Tag 為一組 API 操作新增標籤，以便在文件中組織和分組

@Operation 描述一個 API 操作，包括摘要和詳細描述

java 复制代码

@Operation(summary = "Create Account REST API", description = "REST API to create an account")
    @Tag(name = "Account Controller", description = "Account Management API")
    @PostMapping("/create")
    public ResponseEntity<ResponseDto> createAccount(@Valid @RequestBody CustomerDto customerDto) {
        iAccountsService.createAccount(customerDto);
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(new ResponseDto(AccountsConstants.STATUS_201, AccountsConstants.MESSAGE_201));
    }

@ApiResponse述單一 HTTP 回應狀態碼的詳細資訊

@ApiResponses 描述多個 HTTP 回應狀態碼的詳細資訊

@Content 描述回應內容的類型和格式

java 复制代码

 @Operation(summary = "Create Account REST API", description = "REST API to create an account")
    @ApiResponse(responseCode = "201", description = "HTTP Status Created")
    @PostMapping("/create")
    public ResponseEntity<ResponseDto> createAccount(@Valid @RequestBody CustomerDto customerDto) {
        iAccountsService.createAccount(customerDto);
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(new ResponseDto(AccountsConstants.STATUS_201, AccountsConstants.MESSAGE_201));
    }

java 复制代码

@Operation(summary = "Update an account", description = "REST API to update an account")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "HTTP Status OK"),
            @ApiResponse(responseCode = "417", description = "Expectation Failed", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseDto.class))),
            @ApiResponse(responseCode = "500", description = "Internal Server Error", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseDto.class)))
    })
    @PutMapping("/update")
    public ResponseEntity<ResponseDto> updateAccountDetails(@Valid @RequestBody CustomerDto customerDto) {
        boolean isUpdated = iAccountsService.updateAccount(customerDto);
        if (isUpdated) {
            return ResponseEntity
                    .status(HttpStatus.OK)
                    .body(new ResponseDto(AccountsConstants.STATUS_200, AccountsConstants.MESSAGE_200));
        }
        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(new ResponseDto(AccountsConstants.STATUS_500, AccountsConstants.MESSAGE_500));
    }

@Schema 描述資料模型的屬性和結構，通常用於模型類別或 API 方法的參數和傳回值

java 复制代码

@Data
@Schema(name = "Customer", description = "Schema to hold Customer and Account information")
public class CustomerDto {

    @Schema(description = "Name of the customer", example = "Danny Yu")
    @NotEmpty(message = "Name is required")
    @Size(min = 5, max = 30, message = "Name must be between 5 and 30 characters")
    private String name;

    @Schema(description = "Email of the customer", example = "demo@email.com")
    @NotEmpty(message = "Email is required")
    @Email(message = "Email is invalid")
    private String email;

    @Schema(description = "Mobile number of the customer", example = "1234567890")
    @Pattern(regexp = "\\d{10}", message = "Mobile number must be 10 digits")
    private String mobileNumber;

    @Schema(description = "Account details of the customer", example = "{\"accountNumber\": 1234567890, \"accountType\": \"Savings\", \"branchAddress\": \"123 Main St\"}")
    private AccountsDto accountsDto;
}