백엔드 스터디 Day 9: API 문서와 팀 협업 흐름 읽기

request에는 어떤 필드가 필요한가?
email은 필수인가?
password 최소 길이는 몇 글자인가?
nickname 중복은 허용되는가?
성공하면 id만 오는가, 전체 프로필이 오는가?
이메일 중복이면 HTTP 400인가 409인가?
에러 응답 body에는 message가 있는가?
인증 토큰이 필요한 API인가?

1. 누가 호출할 수 있는가
2. 어떤 URL과 HTTP method를 쓰는가
3. 어떤 request body/query/path parameter가 필요한가
4. 성공 status code와 response body는 무엇인가
5. 실패할 수 있는 조건과 에러 응답은 무엇인가
6. 인증/권한 조건은 무엇인가
7. 예시 요청과 예시 응답은 무엇인가

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
}

http://localhost:8080/swagger-ui/index.html

- endpoint 목록은 나오지만 설명이 없다
- request 필드 설명이 비어 있다
- 에러 응답이 200 성공만 문서화되어 있다
- 인증이 필요한 API인데 Swagger에서 인증 방법을 모른다
- DTO 이름이 CreateRequest, Response처럼 너무 일반적이다
- 예시 값이 없어서 실제 호출 형태를 상상하기 어렵다

@Operation(summary = "회원가입", description = "이메일, 비밀번호, 닉네임으로 새 회원을 생성합니다.")
@ApiResponses({
    @ApiResponse(responseCode = "201", description = "회원가입 성공"),
    @ApiResponse(responseCode = "400", description = "입력값 검증 실패"),
    @ApiResponse(responseCode = "409", description = "이미 사용 중인 이메일")
})
@PostMapping("/api/members")
public ResponseEntity<MemberResponse> create(@Valid @RequestBody MemberCreateRequest request) {
     response  memberServicerequest

public record MemberCreateRequest(
    @Schema(description = "로그인에 사용할 이메일", example = "user@example.com")
    @Email
    String email,

    @Schema(description = "8자 이상 비밀번호", example = "example-password")
    @Size(min = 8)
    String password,

    @Schema(description = "서비스에서 표시할 닉네임", example = "seojing")
    @NotBlank
    String nickname
) {}

# Member API

Spring Boot project.

Run:
./gradlew bootRun

프로젝트가 해결하는 문제
주요 기능 목록
로컬 실행 방법
필수 환경 변수
DB 실행 방법
테스트 실행 방법
Swagger 주소
대표 API 예시
인증이 필요한 API 호출 방법
에러 응답 형식
배포/운영 메모

## Local Run

```bash
./gradlew bootRun --args='--spring.profiles.active=local'
```

## Environment Variables

| name          | required | description                       |
| ------------- | -------- | --------------------------------- |
| `DB_URL`      | yes      | PostgreSQL connection URL         |
| `DB_USERNAME` | yes      | Database user                     |

DB_URL=jdbc:postgresql://localhost:5432/example
DB_USERNAME=example_user
DB_PASSWORD=example-password-placeholder
JWT_SECRET=<secret-placeholder>

내가 처음 이 repo를 받았다고 할 때,
30분 안에 서버를 실행하고,
Swagger를 열고,
대표 API 하나를 호출할 수 있는가?

{
  "displayName": "서징"
}

{
  "nickname": "서징"
}

PATCH /api/members/me/profile
Authorization: Bearer ***
Content-Type: application/json

{
  "nickname": "서징",
  "bio": "프론트엔드와 백엔드를 같이 공부하는 중"
}

{
  "id": 12,
  "email": "user@example.com",
  "nickname": "서징",
  "bio": "프론트엔드와 백엔드를 같이 공부하는 중",
  "updatedAt": "2026-06-09T10:15:00"
}

{
  "code": "INVALID_INPUT",
  "message": "닉네임은 비어 있을 수 없습니다.",
  "fieldErrors": [
    {
      "field": "nickname",
      "reason": "must not be blank"
    }
  ]
}

성공하면 어떤 데이터를 화면에 반영할지
입력값 에러는 어느 필드 아래에 표시할지
권한 에러는 로그인 화면으로 보낼지
중복 에러는 toast로 보여줄지

이메일 중복이면 400인가 409인가?
로그인이 만료되면 401인가 403인가?
권한은 있는데 리소스가 없으면 404인가?
삭제된 글에 접근하면 어떤 message가 오는가?

if (memberRepository.existsByEmail(request.email())) {
    throw new BusinessException(ErrorCode.EMAIL_ALREADY_EXISTS);
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusiness(BusinessException e) {
        ErrorCode code = e.getErrorCode();
        return ResponseEntity.status(code.getStatus()).body(ErrorResponse.from(code));
    }
}

http://localhost:8080/v3/api-docs

API 계약이 기계가 읽을 수 있는 형태로 정리되어 있다

프론트엔드 타입 생성
API 클라이언트 생성
문서 사이트 생성
계약 변경 diff 확인
mock server 생성
테스트 케이스 보조 생성

백엔드는 displayName을 받는데 프론트엔드는 nickname을 보낸다
백엔드는 page를 number로 기대하는데 프론트엔드는 string으로 보낸다
응답에는 sourceFeedId가 있는데 프론트엔드 mapper에서 버린다

1. README를 열어 실행 방법과 API 문서 위치를 확인한다
2. Swagger/OpenAPI가 실제로 뜨는지 확인한다
3. 대표 endpoint 하나를 문서대로 호출해본다
4. Controller의 path/method/request/response가 문서와 맞는지 본다
5. DTO validation이 문서 설명과 맞는지 본다
6. GlobalExceptionHandler와 에러 표가 맞는지 본다
7. 인증이 필요한 API의 security scheme이 문서화되어 있는지 본다
8. 프론트엔드가 필요한 예시 요청/응답이 충분한지 본다
9. OpenAPI JSON을 저장해 변경 diff를 볼 수 있는지 확인한다
10. 문서에 없는 동작이 코드에 숨어 있는지 찾는다

- API 변경 시 Swagger/OpenAPI가 자동으로 갱신된다
- README의 대표 요청 예시가 최신 endpoint와 맞다
- 테스트가 API 계약을 일부 검증한다
- OpenAPI JSON을 CI에서 diff로 확인한다
- breaking change가 있으면 changelog나 PR 설명에 남긴다

- README 예시는 예전 URL을 가리킨다
- Swagger에는 200만 있고 실제 코드는 201을 반환한다
- 프론트엔드는 camelCase를 보내는데 백엔드는 snake_case를 기대한다
- 에러 code가 문서에는 있지만 실제 응답에는 없다
- 인증 토큰 예시가 실제 secret처럼 보이는 문자열이다

Controller, DTO, Service만 만들지 말고
Swagger/OpenAPI annotation, README 실행 방법,
대표 요청/응답 예시, 에러 표까지 함께 갱신해줘.

기능 하나가 들어왔을 때,
요구사항 → API 계약 → 구현 → 테스트 → 배포 → 운영 확인이
어떤 순서로 이어지는가?