1. 개요
이 사용방법(예제)에서는 Swagger의 @ApiOperation 및 @ApiResponse 어노테이션 간의 주요 차이점에 대해 설명합니다.
2. Swagger를 사용한 설명 문서
REST API를 만들 때 적절한 사양도 만드는 것이 중요합니다. 또한 이러한 사양은 읽고 이해할 수 있어야 하며 모든 필수 정보를 제공해야 합니다.
또한 문서에는 API에 대한 모든 변경 사항에 대한 설명이 있어야 합니다. REST API 문서를 수동으로 작성하는 것은 소모적이며 더 중요한 것은 시간이 많이 소요된다는 것입니다. 다행스럽게도 Swagger와 같은 도구가 이 프로세스에 도움이 될 수 있습니다.
Swagger 는 OpenAPI 사양 을 기반으로 구축된 오픈 소스 도구 세트를 나타냅니다 . REST API를 설계, 구축, 문서화 및 사용하는 데 도움이 될 수 있습니다.
Swagger 사양은 REST API를 문서화하기 위한 표준입니다. Swagger 사양을 사용하여 노출된 엔드포인트, 작업, 매개변수, 인증 방법 등과 같은 전체 API를 설명할 수 있습니다.
Swagger는 REST API를 문서화하는 데 도움이 되는 다양한 어노테이션을 제공합니다. 또한 REST API에 대한 응답을 문서화하기 위해 @ApiOperation 및 @ApiResponse 어노테이션을 제공합니다 . 이 예제의 나머지 부분에서는 아래 컨트롤러 클래스를 사용하고 이러한 어노테이션을 사용하는 방법을 살펴보겠습니다.
@RestController
@RequestMapping("/customers")
class CustomerController {
private final CustomerService customerService;
public CustomerController(CustomerService customerService) {
this.customerService = customerService;
}
@GetMapping("/{id}")
public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
return ResponseEntity.ok(customerService.getById(id));
}
}3. @ApiOperation
@ApiOperation 어노테이션은 단일 작업을 설명하는 데 사용됩니다. 작업은 경로와 HTTP 메서드의 고유한 조합입니다.
또한 @ApiOperation 을 사용 하여 성공적인 REST API 호출의 결과를 설명할 수 있습니다. 즉, 이 어노테이션을 사용하여 일반적인 반환 유형을 지정할 수 있습니다.
메서드에 어노테이션을 추가해 보겠습니다.
@ApiOperation(value = "Gets customer by ID",
response = CustomerResponse.class,
notes = "Customer must exist")
@GetMapping("/{id}")
public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
return ResponseEntity.ok(customerService.getById(id));
}다음으로 @ApiOperation 내에서 가장 많이 사용되는 몇 가지 속성을 살펴보겠습니다 .
3.1. 값 속성 _
필수 값 속성에는 작업의 요약 필드가 포함되어 있습니다. 간단히 말해 작업에 대한 간략한 설명을 제공합니다. 그러나 이 매개변수를 120자 미만으로 유지해야 합니다.
다음은 @ApiOperation 어노테이션 내에서 값 속성을 정의하는 방법 입니다.
@ApiOperation(value = "Gets customer by ID")3.2. 메모 속성 _
메모 를 사용 하여 작업에 대한 자세한 내용을 제공할 수 있습니다. 예를 들어 엔드포인트의 제한 사항을 설명하는 텍스트를 배치할 수 있습니다.
@ApiOperation(value = "Gets customer by ID", notes = "Customer must exist")3.3. 응답 속성 _
응답 속성에는 작업의 응답 유형이 포함됩니다 . 또한 이 속성을 설정하면 자동으로 파생된 모든 데이터 유형이 재정의됩니다. @ApiOperation 어노테이션 내부에 정의된 응답 속성 에는 일반 응답 유형이 포함되어야 합니다.
메서드가 반환하는 성공적인 응답을 나타내는 클래스를 만들어 보겠습니다.
class CustomerResponse {
private Long id;
private String firstName;
private String lastName;
// getters and setters
}다음으로 어노테이션에 응답 속성을 추가해 보겠습니다 .
@ApiOperation(value = "Gets customer by ID",
response = CustomerResponse.class,
notes = "Customer must exist")
@GetMapping("/{id}")
public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
return ResponseEntity.ok(customerService.getById(id));
}3.4. 코드 속성 _
code 속성은 응답 코드의 HTTP 상태를 나타냅니다. HTTP 상태 코드 에는 여러 정의가 있습니다 . 그 중 하나를 사용해야 합니다. 제공하지 않으면 기본값은 200입니다.
4. @ApiResponse
HTTP 상태 코드를 사용하여 오류를 반환하는 것이 일반적입니다. @ApiResponse 어노테이션을 사용하여 오퍼레이션 의 가능한 구체적인 응답을 설명할 수 있습니다.
@ApiOperation 어노테이션은 작업 및 일반 반환 유형을 설명하는 반면 @ApiResponse 어노테이션은 가능한 반환 코드의 나머지 부분을 설명합니다.
또한 어노테이션은 클래스 수준뿐만 아니라 메소드 수준에서도 적용될 수 있습니다. 또한 동일한 코드의 @ApiResponse 어노테이션이 메서드 수준에 이미 정의되어 있지 않은 경우에만 클래스 수준에 추가된 어노테이션이 구문 분석됩니다 . 즉, 메서드 어노테이션이 클래스 어노테이션보다 우선합니다.
응답이 하나이든 여러 개이든 관계없이 @ApiResponses 어노테이션 내에서 @ApiResponse 어노테이션 을 사용해야 합니다 . 이 어노테이션을 직접 사용하면 Swagger에서 구문 분석하지 않습니다.
메서드에서 @ApiResponses 및 @ApiResponse 어노테이션을 정의해 보겠습니다 .
@ApiResponses(value = {
@ApiResponse(code = 400, message = "Invalid ID supplied"),
@ApiResponse(code = 404, message = "Customer not found")})
@GetMapping("/{id}")
public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
return ResponseEntity.ok(customerService.getById(id));
}어노테이션을 사용하여 성공 응답도 지정할 수 있습니다.
@ApiOperation(value = "Gets customer by ID", notes = "Customer must exist")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK", response = CustomerResponse.class),
@ApiResponse(code = 400, message = "Invalid ID supplied"),
@ApiResponse(code = 404, message = "Customer not found"),
@ApiResponse(code = 500, message = "Internal server error", response = ErrorResponse.class)})
@GetMapping("/{id}")
public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
return ResponseEntity.ok(customerService.getById(id));
}@ApiResponse 어노테이션 을 사용하여 성공적인 응답을 지정하면 @ApiOperation 어노테이션 내부에 정의할 필요가 없습니다 .
이제 @ApiResponse 내에서 사용되는 몇 가지 속성을 살펴보겠습니다 .
4.1. 코드 및 메시지 속성 _
코드 및 메시지 속성은 모두 @ApiResponse 어노테이션의 필수 매개변수입니다.
@ApiOperation 어노테이션 내부의 코드 속성과 마찬가지로 응답의 HTTP 상태 코드를 포함해야 합니다. 동일한 코드 속성으로 하나 이상의 @ApiResponse 를 정의할 수 없다는 점을 언급하는 것이 중요합니다.
메시지 속성에는 일반적으로 응답과 함께 사람이 읽을 수 있는 메시지가 포함됩니다.
@ApiResponse(code = 400, message = "Invalid ID supplied")4.2. 응답 속성 _
경우에 따라 엔드포인트는 다른 응답 유형을 사용합니다. 예를 들어 성공 응답에 대한 유형과 오류 응답에 대해 다른 유형을 가질 수 있습니다. 응답 클래스를 응답 코드와 연결 하여 선택적 응답 속성을 사용하여 설명할 수 있습니다 .
먼저 내부 서버 오류가 발생할 경우 반환될 클래스를 정의해 보겠습니다.
class ErrorResponse {
private String error;
private String message;
// getters and setters
}둘째, 내부 서버 오류에 대한 새 @ApiResponse 를 추가해 보겠습니다.
@ApiResponses(value = {
@ApiResponse(code = 400, message = "Invalid ID supplied"),
@ApiResponse(code = 404, message = "Customer not found"),
@ApiResponse(code = 500, message = "Internal server error", response = ErrorResponse.class)})
@GetMapping("/{id}")
public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
return ResponseEntity.ok(customerService.getById(id));
}5. @ApiOperation 과 @ApiResponse 의 차이점
요약하면 다음 표는 @ApiOperation 및 @ApiResponse 어노테이션 간의 주요 차이점을 보여줍니다 .
| @ApiOperation | @ApiResponse |
|---|---|
| 작업을 설명하는 데 사용 | 작업의 가능한 응답을 설명하는 데 사용됩니다. |
| 성공적인 응답에 사용 | 성공 및 오류 응답에 사용 |
| 메서드 수준에서만 정의할 수 있습니다. | 메서드 또는 클래스 수준에서 정의할 수 있습니다. |
| 직접 사용할 수 있습니다 | @ApiResponses 어노테이션 내에서만 사용할 수 있습니다. |
| 기본 코드 속성 값은 200입니다. | 기본 코드 속성 값이 없습니다. |
6. 결론
이 기사에서는 @ApiOperation 과 @ApiResponse 어노테이션 의 차이점을 배웠습니다 .
항상 그렇듯이 예제의 소스 코드는 GitHub에서 사용할 수 있습니다 .
