[Spring] Swagger Api문서 작성하기

주요 어노테이션

• @Api : 해당 어노테이션을 설명합니다
• @ApiOperation(value = "제목", note = "설명")
• @ApiImplicitParam(name = "파라미터", value = "파라미터 값")
• @ApiIgnore : 명세서에 표시하지 않는 것을 의미합니다.
• @ApiModelProperty : dto에 작성. 예시를 넣을 수 있습니다.

주로 컨트롤러에서 사용되고 @ApiModelProperty만 dto에서 사용됩니다.

컨트롤러

@Api

@Api 어노테이션을 통해 아래와 같이 Controller의 명칭을 변경할 수 있습니다.

@Api(tags = {"게시글 API"})  // Swagger 최상단 Controller 명칭
public class BoardController {
	...
}

@ApiOperation

@ApiOperation을 사용하면 해당 Api의 설명을 추가할 수 있습니다.

@DeleteMapping("/board/{id}")
@ApiOperation(value = "게시글 삭제", notes = "해당 id를 가지는 게시글을 삭제합니다.")

@ApiImplicitParam

위의 코드에서 @ApiImplicitParam 어노테이션을 추가하면 파라미터로 사용되는 것에 설명도 추가할 수 있습니다.

@DeleteMapping("/board/{id}")
@ApiOperation(value = "게시글 삭제", notes = "해당 id를 가지는 게시글을 삭제합니다.")
@ApiImplicitParam(name = "id", value = "게시글 생성시 발급되는 id")

DTO

@ApiModelProperty 

@ApiModelProperty를 사용하여 Request 할 때 예시를 입력해줄 수 있습니다.

@ApiModelProperty(example = "제목")
private String title;
@ApiModelProperty(example = "본문")
private String content;
@ApiModelProperty(example = "작성자")
private String author;
@ApiModelProperty(example = "최초로 작성시간")
private LocalDateTime createdTime;
@ApiModelProperty(example = "마지막으로 수정한 시간")
private LocalDateTime modifiedTime;

Try it out을 누르면 위의 Example Value가 그대로 들어가 있는 것을 확인할 수 있습니다.

이렇게 Api 문서를 쉽게 생성하고 수정하는 방법을 알아봤습니다.