Swagger: 일반적인 오류 응답은 표기하지 않는 것이 좋을까요?

[merge-simpson]

마침 팀이 API 문서를 먼저 작성하기로 하고, 일차적으로는 완성했다고 생각하는데요.
스펙 수정이 필요한 API도 보이지만, 우선 목록 제공까지는 완성한 것으로 보입니다.

이 과정에서 예외 응답 등 응답의 목록에 관해 조금 고민한 부분이 있었는데요.

Background

우선 우리가 스프링부트에서 애노테이션 기반으로 swagger 스펙을 작성할 때, 다음 예시의 responses처럼 응답 목록을 제공할 수 있습니다.

@GetMapping("/{blogId}")
@Operation(
        summary = "블로그 상세 조회",
        description = "블로그 정보를 조회합니다.",
        responses = {
                @ApiResponse(
                        responseCode = "200",
                        description = "OK"
                ),
                @ApiResponse(
                        responseCode = "404",
                        description = "블로그를 찾을 수 없습니다.",
                        content = {@Content(schema = @Schema(implementation = ApiErrorResponse.class))}
                )
        }
)
public BlogDetailViewResponse findByBlogId(@PathVariable("blogId") String blogId) {/* ... */}

Discussion

일부 예외 응답은 특별한 예외가 아니며, 거의 모든 API에서 제공될 수 있습니다. 이러한 예외 응답도 모든 API에 제공하려면 별도 설정을 추가할 수 있는 것으로 알고 있구요.

다만 그것이 API docs에서 의미 있는 정보 전달인지 의구심이 있어서 모두의 생각을 들어보고 싶습니다.

1. 일반적인 예외 응답도 API 문서에 모두 작성하는 것이 좋을까요?
   단, 예외 응답의 스키마에 대해서는 별도로 커뮤니케이션이 필요하다고 생각합니다.
2. 특수한 예외 응답일 때는 API 문서에 작성하는 것이 당연하다고 생각하는데, 다들 비슷하게 생각하실까요?
3. 관련하여 논의가 필요한 항목이 더 있을까요?

많은 참여 부탁드리겠습니다.

[merge-simpson]

우리 깃허브 디스커션이라는 기능을 제거하고 디스코드에서만 논의할까요?
깃허브 디스커션은 외부에 보여주는 효과가 있어서 시작한 것도 있고, 디스코드 대비 마크다운과 일부 입력 기능을 더 편하게 쓸 수 있어서 장점이 있습니다.

근데 다른 활동 대비 깃허브 디스커션만 참여율이 떨어지네요

@silberbullet
@wch-os
@sweetykr7
@wowddok99
@seonghooni