fix: auth reissue Swagger 계약과 Orval generated 함수 시그니처 불일치 정리

[haewonwon]

배경

현재 live Swagger(/v3/api-docs) 기준 토큰 갱신 API는 다음 계약입니다.

• POST /auth/reissue
• Header: Authorization required
• Body: { device_id: string }
• Response: { access_token, refresh_token }

하지만 Orval generated 함수는 Authorization header를 명시적 파라미터로 노출하지 않습니다.

export const reissue = (
  tokenReissueRequestDto: BodyType<TokenReissueRequestDto>,
  options?: SecondParameter<typeof apiMutator>,
  signal?: AbortSignal,
) => {
  return apiMutator<TokenReissueResponseDto>(
    {
      url: `/auth/reissue`,
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      data: tokenReissueRequestDto,
      signal,
    },
    options,
  );
};

따라서 호출자가 Swagger 계약을 직접 확인하지 않으면 refresh token bearer header를 누락하기 쉽습니다.

현재 조치

generated 파일은 직접 수정하지 않고, domain wrapper/interceptor에서 다음 방식으로 보완합니다.

reissue(
  { device_id: deviceId },
  {
    headers: {
      Authorization: `Bearer ${refreshToken}`,
    },
  },
);

자동 갱신 interceptor도 raw axios로 /auth/reissue를 호출하되, Swagger 계약에 맞춰 Authorization: Bearer ${refreshToken}과 { device_id }를 함께 보냅니다.

확인 필요

• Orval 설정 또는 Swagger 표현 방식 때문에 required header가 타입으로 강제되지 않는 현재 상태를 유지할지 확인
• 백엔드 Swagger에서 Authorization을 endpoint parameter로 둘지, 전역 security scheme으로 정리할지 검토
• refresh token 기반 API는 generated 함수만 보고도 누락 없이 사용할 수 있도록 wrapper 규칙 문서화 필요

완료 기준

• /auth/reissue 호출 시 refresh token bearer header가 항상 포함됨
• generated DTO/endpoint 직접 import는 domain API boundary 안에서만 사용됨
• Swagger 계약과 wrapper 구현이 불일치하지 않음
• accessToken 만료 후 401/403 → reissue → token 저장 → 원 요청 재시도 흐름이 실제 기기/시뮬레이터에서 확인됨