콘텐츠로 이동

API 명세화 (SpringDoc / Swagger)

SpringDoc이 @RestController/@RequestMapping을 자동 스캔해 OpenAPI 문서를 생성. 일반 컨트롤러 코드만으로 기본 문서화됨.

1. 커스터마이징 어노테이션

어노테이션 용도
@Operation(summary, description) API 메서드 설명
@Parameter(description) 파라미터 설명
@Schema(description, example) DTO 필드 설명
@Hidden 문서에서 제외(내부 API) 
@Operation(summary = "사용자 조회", description = "ID로 사용자 조회")
@GetMapping("/{id}")
public ResponseEntity<UserDto> getUser(
    @Parameter(description = "사용자 ID") @PathVariable Long id) { ... }

2. 에러 명세

에러 응답은 도메인별 메타 어노테이션으로 자동 노출 — 상세는 teams/engineering/guides/exception-handling §5.

@ApiMemberErrorResponses({ MemberErrorCode.MEMBER_NOT_EXIST })
@ApiAuthErrorResponses({ AuthErrorCode.ACCESS_DENIED })  // 다중 도메인 조합 가능
@GetMapping("/api/members/info")
public SuccessResponse<Member> getMemberInfo(...) { }

3. 경로 / role prefix 관례

엔드포인트는 접근 주체별 prefix를 둠 (raw API 명세 기준): - /api/public/** — 비로그인 허용 (Spring Security permitAll) - /api/student/**, /api/teacher/** — 역할별 - /api/notification, /common/media/** 등 공통

자세한 표면은 도메인 페이지 §API 표면 참조: teams/engineering/domains/qna, teams/engineering/domains/challenge.

4. 관련