Skip to content
swagger-to-tanstack-query

규칙과 설계 결정

생성된 코드에 담긴 규칙과 트레이드오프를 설명합니다.

생성기는 고정된 규칙을 따르므로 출력 결과를 예측할 수 있습니다. 아래는 그러한 결정들과 그 이면의 트레이드오프입니다.

규칙

  • GET/HEAD는 쿼리, 그 외 전부는 mutation입니다.
  • 단일 객체 인자: 모든 api/query/mutation은 { ...pathParams, body, params, headers } 키를 가진 객체 하나를 받습니다. 순서에 영향을 받지 않으며 path 파라미터가 여럿일 때도 안전합니다. 입력이 없는 함수는 인자를 받지 않습니다.
  • params/headers 객체는 그 안의 파라미터가 모두 선택적일 때만 선택적입니다.
  • 응답은 첫 번째 2xx 응답의 application/json 스키마를 사용합니다(없으면 default로, 그다음 void로 폴백합니다).
  • 여러 태그가 달린 operation은 태그가 지정된 모든 컨트롤러에 생성됩니다 (Swagger UI가 그룹을 묶는 방식과 동일합니다).
  • 컨트롤러별로 독립적으로 완결되는 타입. 두 컨트롤러가 참조하는 스키마는 양쪽 types.ts 파일에 모두 생성됩니다. 약간의 중복을 감수하는 대신 각 폴더의 독립성을 유지합니다.
  • 출력 디렉터리는 매 실행마다 비워지므로 스펙에서의 삭제가 그대로 반영됩니다. 생성된 파일은 절대 직접 수정하지 마세요. 파일에는 AUTO-GENERATED 헤더가 붙어 있습니다.

관련 문서