devYuraKim / devYuraKim/microservices
Swagger API Documentation: Improve error response examples and endpoint error mapping
- Dominant language
- Java
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
**Description:**
- Problem 1: Swagger examples have not been fully verified; some error responses currently show success examples.
```
HTTP Status 400 Bad Request
Example Value
{
"code": 200,
"status": "OK",
"message": "Request processed successfully",
"data": "string",
"path": "/api/create",
"timestamp": "2025-08-28T08:29:08.601Z"
}
```
- Problem 2: Specifying errors for each endpoint in the documentation is cumbersome and prone to human error.
Errors are handled globally and usually thrown in the service layer, so documenting them for each endpoint requires navigating multiple files to identify possible errors.
`AccountsController`
```
@Operation(summary = "Fetch Account details", description = "Fetch Customer and Account details based on the given mobile number")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "HTTP Status 200 OK"),
@ApiResponse(responseCode = "400", description = "HTTP Status 400 Bad Request", content=@Content(schema=@Schema(implementation=ApiResponseDto.class))),
@ApiResponse(responseCode = "404", description = "HTTP Status 404 Not Found", content=@Content(schema=@Schema(implementation=ApiResponseDto.class)))
})
@GetMapping("/fetch")
public ResponseEntity> fetchAccountDetails(@RequestParam @Pattern(regexp = "^\\d{11}$", message="Mobile number must be 11 digits") String mobileNumber){
CustomerDto customerDto = iAccountsService.fetchAccount(mobileNumber);
return ApiResponseBuilder.buildSuccessResponse(HttpStatus.OK, AccountsConstants.MESSAGE_200, customerDto);
}
```
`AccountsServiceImpl`
```
@Override
public CustomerDto fetchAccount(String mobileNumber) {
Customer customer = customerRepository.findByMobileNumber(mobileNumber).orElseThrow(
() -> new ResourceNotFoundException("Customer", "mobileNumber", mobileNumber));
Accounts accounts = accountsRepository.findByCustomerId(customer.getCustomerId()).orElseThrow(
() -> new ResourceNotFoundException("Accounts", "customerId", customer.getCustomerId().toString()));
CustomerDto customerDto = CustomerMapper.mapToCustomerDto(customer, new CustomerDto());
customerDto.setAccountsDto(AccountsMapper.mapToAccountsDto(accounts, new AccountsDto()));
return customerDto;
}
```
**Proposed goal:**
- Ensure Swagger shows accurate error examples for each API endpoint.
- Investigate a more automated or centralized approach to define endpoint errors (e.g., a shared error registry or annotations at the service layer) to reduce human error.
**Notes / Additional context:**
- This issue does not block current API functionality, but improving docs will help developers understand error responses more clearly.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.