devYuraKim / devYuraKim/microservices

Swagger API Documentation: Improve error response examples and endpoint error mapping

Open
#12 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.