Swagger API 문서화

📄 요구 사항

아래 API에 대해 API 문서를 작성해라.

1. 게시글 작성 기능
2. 게시글 전체 조회 기능
3. 특정 게시글 조회 기능
4. 특정 게시글 수정 기능
5. 특정 게시글 삭제 기능
6. 게시글 검색 기능

---

제약 조건

• Swagger, Github Wiki, Notion, Postman, Gitbook 중 사용하기
• API 문서에 아래의 내용은 반드시 포함시키기
  • URL 주소 / HTTP 메서드
  • API 설명
  • 요청 형태
    • Path Parmas
    • Query Params
    • Body Params
    • 필수 여부
    • 데이터 타입
  • 응답 형태
    • 응답 코드(status code)
    • 각 응답 코드별 설명
    • 응답 형태 (response value)
    • 응답 값에서 각 파라미터의 의미
    • 응답 값에서 각 파라미터의 필수 여부
    • 응답 값에서 각 파라미터의 데이터 타입

---

OpenApiConfig

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI(){
        Info info = new Info()
                .title("익명 게시판 API 문서")
                .version("v0.0.1")
                .description("익명 게시판의 API 문서입니다.");
        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}

• 해당 Config파일을 통해서 API에 대한 제목, 버전, 설명을 달 수 있다.

결과

---

PostController

@RestController
@RequestMapping("/boards")
@RequiredArgsConstructor
public class PostController {

    private final PostService postService;

    @Operation(summary = "게시글 조회", description = "해당 id의 게시글 조회")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "게시글 조회 성공",
                    content = @Content(schema = @Schema(implementation = PostResponse.class))),
            @ApiResponse(responseCode = "404", description = "존재하지 않는 게시글 조회",
                    content = @Content(schema = @Schema(implementation = ErrorResult.class)))
    })
    @GetMapping("/{postId}")
    public PostResponse getPost(@Parameter(description = "게시글의 id", in = ParameterIn.PATH)
                                @PathVariable Long postId) {

        return postService.findPost(postId);
    }

    @Operation(summary = "게시글 생성", description = "요청 DTO에 담긴 데이터로 게시글 생성")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "게시글 생성 성공" ,
                    content = @Content(schema = @Schema(implementation = PostResponse.class))),
            @ApiResponse(responseCode = "400", description = "잘못된 요청",
                    content = @Content(schema = @Schema(hidden = true)))
    })
    @PostMapping
    public ResponseEntity<PostResponse> createPost(@Valid @RequestBody PostRequest postRequest){

        PostResponse saveResponse = postService.writePost(postRequest);
        return ResponseEntity.ok(saveResponse);
    }

    @Operation(summary = "게시글 수정", description = "해당 id의 게시글을 요청 DTO에 담긴 데이터로 수정")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "게시글 수정 성공",
                    content = @Content(schema = @Schema(implementation = PostResponse.class))),
            @ApiResponse(responseCode = "404", description = "존재하지 않는 게시글 조회",
                    content = @Content(schema = @Schema(implementation = ErrorResult.class)))
    })
    @PatchMapping("/{postId}")
    public PostResponse modifyPost(@Parameter(description = "게시글의 id", in = ParameterIn.PATH)
                                   @PathVariable Long postId,
                                   @Valid @RequestBody PostRequest postRequest) {

        return postService.modifyPost(postId, postRequest);
    }

    @Operation(summary = "게시글 삭제", description = "해당 id의 게시글 삭제")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "게시글 삭제 성공",
                    content = @Content(schema = @Schema(implementation = PostResponse.class))),
            @ApiResponse(responseCode = "404", description = "존재하지 않는 게시글 조회",
                    content = @Content(schema = @Schema(implementation = ErrorResult.class)))
    })
    @DeleteMapping("/{postId}")
    public ResponseEntity deletePost(@Parameter(description = "게시글의 id", in = ParameterIn.PATH)
                             @PathVariable Long postId) {

        postService.deletePost(postId);
        return ResponseEntity.ok("성공적으로 삭제되었습니다.");
    }

    @Operation(summary = "게시글 검색", description = "검색 키워드를 통해 게시글 제목을 검색")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "게시글 검색 성공",
                    content = @Content(schema = @Schema(implementation = PostResponse.class))),
            @ApiResponse(responseCode = "400", description = "검색 키워드가 조건에 맞지 않음",
                    content = @Content(schema = @Schema(implementation = ErrorResult.class)))
    })
    @GetMapping
    public List<PostResponse> searchPostTitle(@RequestParam("keyword") String keyword) {

        return postService.searchPostTitleList(keyword);
    }

    @Operation(summary = "게시글 모두 조회", description = "모든 게시글을 조회")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "게시글 조회 성공",
                    content = @Content(schema = @Schema(implementation = PostResponse.class))),
            @ApiResponse(responseCode = "400", description = "잘못된 요청",
                    content = @Content(schema = @Schema(hidden = true)))
    })
    @GetMapping("/list")
    public List<PostResponse> findAllPost(){
        return postService.findAllPosts();
    }

}

• @Operation 애노테이션은 API 작업에 대한 다양한 속성을 지정할 수 있다. summary는 API 작업에 대한 간단한 요약을 할 수 있습니다. description는 API 작업에 대한 자세한 설명을 할 수 있습니다.

• @ApiResponse 애노테이션을 사용하여 API 작업의 응답 형식을 정의할 수 있다. responseCode, description로 코드와 그 코드에 대한 설명을 할 수 있다. 그리고 content를 통해 응답 내용을 담을 수 있는데, @Content를 사용해서 schema를 통해 응답 스키마를 지정할 수 있다.
  hidden을 통해 응답에 대한 내용을 가릴 수 있다.

• @Paramater 애노테이션을 사용하여 매개변수를 정의할 수 있다. description를 통해서 매개변수에 대한 설명을 할 수 있다.

결과

---

PostResponse

@Getter
public class PostResponse {

    @Schema(description = "게시판 id")
    private final Long id;

    @Schema(description = "게시판 제목")
    private final String title;

    @Schema(description = "게시판 내용")
    private final String content;

    @Schema(description = "게시판 생성일자")
    private final LocalDateTime regTime;

    public PostResponse(Post post) {
        this.id = post.getId();
        this.title = post.getTitle().getValue();
        this.content = post.getContent().getValue();
        this.regTime = post.getRegTime();
    }

}

• @Schema를 통해서 해당 스키마에 대한 설명을 달 수 있다.

결과

---

📒 나의 생각

• @Paramater 애노테이션을 통해서 파라미터를 name으로 수정하는 것이 적용되지 않는다. @Paramater 애노테이션을 적용하게 될 경우 Swagger에서 파라미터가 아예 없어지는 현상이 발생한다. 이 부분은 아직 해결하지 못했다.
• springdoc은 애노테이션을 통해서 명세화를 하는데, 컨트롤러 부분에 애노테이션이 많이 달리게 되서 가독성이 떨어지게 된다. spring rest docs에 대해서도 학습이 필요할 것 같다.
• API 명세서에서 예상되는 예외를 다루기 위해서 에러코드에 대한 학습과, 예상되는 에러에 대해서 예외처리를 연습이 필요할 것 같다.