📜 스웨거 가이드라인 📜

응답 및 예외 처리 방식

1. 응답(200) 작성 방식

• @ResponseCodeAnnotation를 사용한다.

• @ResponseCodeAnnotation(CommonResponseCode.코드이름)를 컨트롤러에 어노테이션으로 넣으면 된다.

• @ResponseCodeAnnotation 어노테이션을 사용하지 않는다면 자동으로 200으로 처리된다.

  

  위 사진과 같이 CREATED는 CREATED라고 어노테이션을 사용해서 Swagger에 알려주는 모습.

2. 예외(4XX, 5XX) 작성 방식

• @ExceptionCodeAnnotations를 사용한다.

• @ExceptionCodeAnnotations({CommonExceptionCode.코드이름, CommonExceptionCode.코드이름})

• 응답 방식과 다르게 {}를 사용해서 배열 형태로 넘겨준다. 이유는 여러 예외가 발생할 수 있다고 알려줘야 하기 때문.

• 예외가 1개여도 {}안에 넣어야 한다.

  

  위 사진은 BAD_GATEWAY, BAD_REQUEST를 반환하는 모습. 어노테이션을 사용하지 않는다면 스웨거에는 예외가 적히지 않는다.

3. 추가

• @ApiResponses, @ApiResponse 를 사용 할 수는 있으나 자동으로 응답 형식, 예외 형식을 맞춰주지 않음 사용하지 않는 게 좋다. 아니 사용하지 말자

• 좀 더 사용을 편리하게, 구속되지 않고 사용할 수 있도록 만들라고 했으나 실력 부족으로 인해 오히려 제약이 생겨버린 모순.

  • 결론 : 봐주세요.

Swagger 버전 및 의존성

• Springdoc-openapi를 사용한 OpenAPI 3.0 스펙을 바탕으로 글을 작성했다.

0. Gradle 의존성

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

1. @Operation 설정 및 모델 객체 필드 설명

@Operation(
    summary = "User login", 
    description = "사용자가 로그인할 때 사용하는 엔드포인트"
)
@PostMapping(value = "/user3/{id}")
public UserSwagger postUser3(
    @PathVariable Long id,
    @RequestBody(description = "로그인에 필요한 사용자 정보", required = true, content = @Content(
            mediaType = "application/json", 
            schema = @Schema(implementation = UserSwagger.class)
    )) UserSwagger user) {
    return user;
}

• @Operation은 API 문서에 설명을 적을 수 있다.

  • summary : 엔드포인트 간단 설명

  • description : 엔드포인트 상세 설명

  • @Content : 메타 데이터 정의 및 schema 설정

  • mediaType : 메타 데이터 설정 생략 가능

  • schema : 필요한 객체 지정

2. @Schema 설정 및 객체 필드 설명

@Schema(description = "스웨거 설명용 사용자")
@Getter
class UserSwagger {
    Integer id = 2759;

    @Schema(description = "사용자 이름", required = true, example = "잠자고싶어요")
    String name = "gnoDgnoD";

    @Schema(description = "사용자 이메일", required = true, example = "user@example.com")
    String email = "Aleph@tistory.com";
}

• @Schema를 통해서 객체의 필드값 설명을 추가할 수 있다.

  • description: schema에서 설명할 필드의 값

  • example: example Value에 들어갈 예시 값

    

3. 각각의 파라미터별 문서 작성하는 방법

3-1. @PathVariable

@GetMapping("/user/{id}")
public String getPathVariable(
    @Parameter(description = "사용자 id", required = true) 
    @PathVariable String id) {
    return id;
}

• Request : GET /user/123

3-2. @RequestParam

@GetMapping("/user")
public String getRequestParam(
    @Parameter(description = "쿼리를 입력해주세요") 
    @RequestParam String name) {
    return name;
}

• Request : GET /user?name=Name

3-3. @RequestBody

@RestController
@RequestMapping("/api")
public class UserController {

    @PostMapping("/user")
    @Operation(
        summary = "사용자 로그인", 
        description = "사용자 로그인 API입니다."
    )
    public Item createItem(
        @RequestBody(description = "생성할 아이템의 정보", required = true, content = @Content(
            schema = @Schema(implementation = Item.class)
        )) Item item) {
        return item;
    }
}

• Request : POST /user 에 있는 RequestBody 값

3-4. @RequestHeader

@GetMapping("/user")
public String getRequestHeader(
    @Parameter(description = "Authorization token") 
    @RequestHeader("Authorization") String authorization) {
    return authorization;
}

• Request : GET /request-header의 헤더에 담겨있는 Authorization: Bearer token

3-5. @CookieValue

@GetMapping("/user")
public String getCookieValue(
    @Parameter(description = "Session id값을 가져옴") 
    @CookieValue("sessionId") String sessionId) {
    return sessionId;
}

• Request : GET /user의 쿠키에 담겨있는 Cookie sessionId=abc123

3-6. @ModelAttribute

@PostMapping("/user")
public String createWithModelAttribute(
    @Parameter(description = "생성할 아이템의 정보", required = true, schema = @Schema(implementation = Item.class))
    @ModelAttribute Item item) {
    return "Created item: " + item;
}

• Request : POST /user 에 있는 Model 값

3-7. @RequestPart

@PostMapping("/user")
public String uploadFile(
    @Parameter(description = "업로드할 파일") 
    @RequestPart("file") MultipartFile file) {
    return file.getOriginalFilename();
}

4. RestController 설명 추가하기

@Tag

@RestController
@RequestMapping("/api")
@Tag(name = "User Management", description = "사용자 관리와 관련된 API")
public class UserController

• Operation과 각각의 파라메터 별 문서 작성법을 둘다 사용하면 된다!