API 명세 작성

Swagger(OpenAPI) 명세를 작성하는 방법을 설명합니다. 예제 코드를 기반으로, 각 어노테이션과 그 의미를 설명합니다.

시작하기

어노테이션 설명

기본적으로 작성이 필요한 어노테이션은 다음과 같습니다.

• @Tag : API 그룹에 대한 설명을 추가합니다.
• @Api : API 메서드에 대한 설명을 추가합니다.
• @Parameter : API 메서드의 파라미터에 대한 설명을 추가합니다.
• @Schema : 데이터 항목의 설명을 추가합니다.

예제 코드

계정정보를 관리하는 RESTful API를 참고하여, 다음과 같이 Swagger 어노테이션을 작성합니다.

Controller

Swagger UI에서 이 컨트롤러를 계정정보 그룹으로 묶어줍니다.

@Tag(name = "계정정보")
class WorkspaceController {
  // ...
}

Method (Mapping Method)

이 메서드에 대한 요약 및 상세 설명을 추가합니다.

@Api(summary = "계정 목록 조회", description = "모든 계정 정보를 조회합니다.")
public List<WorkspaceReadDto> getWorkspaces() {
  // ...
}

또는

@Api({"계정 목록 조회", "모든 계정 정보를 조회합니다."})
public List<WorkspaceReadDto> getWorkspaces() {
  // ...
}

description 을 제외하고 쓰려고 하면,

@Api("계정 목록 조회")
public List<WorkspaceReadDto> getWorkspaces() {
  // ...
}

이렇게 가능 합니다.

Parameter

메서드 파라미터에 대한 설명과 예시를 추가합니다.

@Parameter(description = "회원사ID", example = "-1") Long tenantId

DTO

필드에 대한 제목, 설명, 예시를 추가합니다.

record WorkspaceDto (
  @Schema(title = "시작일자")
  LocalDateTime from,
  
  @Schema(title = "종료일자")
  LocalDateTime to,
  
  @Schema(title = "검색어")
  String keyword
) {
  // ...
}

HTTP Status

이 메서드의 @ResponseStatus(CREATED) 상태 코드를 설정하면 해당 내용으로 결과가 자동 정의 됩니다.

@Api({"계정 목록 조회", "모든 계정 정보를 조회합니다."})
@ResponseStatus(CREATED)
public List<WorkspaceReadDto> getWorkspaces() {
  // ...
}

Return Type

메서드의 반환 타입 List<WorkspaceReadDto> 에 따라서 응답 결과가 자동 생성됩니다.

@Api({"계정 목록 조회", "모든 계정 정보를 조회합니다."})
@ResponseStatus(CREATED)
public List<WorkspaceReadDto> getWorkspaces() {
  // ...
}

{
  "id": 0,
  "tenantId": 0,
  "name": "string",
  "description": "string"
}

Payload

요청 본문을 @Valid @RequestBody WorkspaceCreateDto workspace 객체로 매핑하고 유효성 검사 결과가 자동으로 생성 됩니다.

WorkspaceController.java

@Api({"계정 목록 조회", "모든 계정 정보를 조회합니다."})
@ResponseStatus(CREATED)
public List<WorkspaceReadDto> getWorkspaces(@Valid @RequestBody WorkspaceCreateDto workspace) {
  // ...
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request content.",
  "instance": "/ce/v1/workspaces/-1",
  "invalids": [
    {
      "field": "name",
      "message": "length must be between 2 and 16",
      "code": "Length",
      "codes": [
        "Length.workspaceCreateDto.name",
        "Length.name",
        "Length.java.lang.String",
        "Length"
      ]
    }
  ]
}