openapi 스펙을 활용해서 type-safe하게 react-query 사용하기

# output parameter를 사용하면 어디에 type을 생성할지 결정할 수 있습니다.
npx openapi-typescript https://api.openapi-generator.tech/api-docs --output ./src/types/index.ts

* paths interface
  - 요청 api endpoint(ex. /api/gen/clients)를 키로하고 어떤 method들을 지원하고 각 method는 어떤 response를 return하는지에 대한 interface입니다.
* operations interface
  - paths에서 각 method들의 parameters(path, query)와 response에 대한 type들을 모아두고 있는 interface입니다.

import { O } from 'ts-toolbelt'

import { paths } from './types'

// 생성된 paths interface의 모든 키들의 type
export type OAIPathKeys = keyof paths
// 주로 사용되는 api method들에 대한 type
export type OAIMethods = 'get' | 'put' | 'post' | 'delete' | 'patch'
// 특정 method가 존재하는 paths key들만 뽑기 위한 type
export type OAIMethodPathKeys<TMethod extends OAIMethods> = O.SelectKeys<
  paths,
  Record<TMethod, unknown>
>

// 특정 paths, method에 해당되는 path parameters type (api params에 대한 type)
export type OAIPathParameters<TPath extends OAIPathKeys, TMethod extends OAIMethods> = O.Path<
  paths,
  [TPath, TMethod, 'parameters', 'path']
>
// 특정 paths, method에 해당되는 query parameters type (api querystring에 대한 type)
export type OAIQueryParameters<TPath extends OAIPathKeys, TMethod extends OAIMethods> = O.Path<
  paths,
  [TPath, TMethod, 'parameters', 'query']
>
// react-query의 variables로 params, querystring을 통합해서 받아서 사용하기 위한 type
export type OAIParameters<
  TPath extends OAIPathKeys,
  TMethod extends OAIMethods
> = OAIPathParameters<TPath, TMethod> extends Record<string, unknown>
  ? OAIQueryParameters<TPath, TMethod> extends Record<string, unknown>
    ? O.Merge<OAIPathParameters<TPath, TMethod>, OAIQueryParameters<TPath, TMethod>>
    : OAIPathParameters<TPath, TMethod>
  : OAIQueryParameters<TPath, TMethod> extends Record<string, unknown>
  ? OAIQueryParameters<TPath, TMethod>
  : undefined

// 특정 path, method의 statusCode 200에 대한 response type
export type OAIResponse<TPath extends keyof paths, TMethod extends OAIMethods> = O.Path<
  paths,
  // 아래의 path는 주어진 OpenApi Specs에 따라서 달라질 수 있습니다.
  [TPath, TMethod, 'responses', 200, 'schema']
>

import type { UseQueryOptions } from 'react-query'
import { useQuery } from 'react-query'

// BASE_URL은 요청해야하는 서버의 주소로 변경 필요
const BASE_URL = 'https://api.openapi-generator.tech'

// useQuery에 전달한 queryKey, variables를 requestUrl로 만들기 위한 utils
export const getRequestUrl = (queryKey: string, variables?: Record<string, unknown>) => {
  let url = `${BASE_URL}${queryKey}`

  const paramKeys = (queryKey.match(/{[a-zA-z-]+}/g) ?? []).map((param) =>
    param.replace(/[{}]/g, '')
  )
  paramKeys.forEach((param) => {
    url = url.replace(`{${param}}`, variables?.[param] as string)
  })

  const qs = new URLSearchParams(
    Object.entries(variables ?? {}).reduce((current, [key, value]) => {
      if (paramKeys.includes(key)) {
        return current
      }

      return {
        ...current,
        [key]: value,
      }
    }, {})
  ).toString()

  if (qs) {
    url = `${url}?${qs}`
  }

  return url
}

// 위에 생성한 types, utils을 활용하여 useQuery를 wrapping하고 있는 useOAIQuery
export function useOAIQuery<
  TQueryKey extends OAIMethodPathKeys<'get'>,
  TVariables extends OAIParameters<TQueryKey, 'get'>,
  TData extends OAIResponse<TQueryKey, 'get'>
>({
  queryKey,
  queryOptions,
  variables,
}: {
  queryKey: TQueryKey
  queryOptions?: Omit<
    UseQueryOptions<TData, unknown, TData, (Record<string, unknown> | TQueryKey | undefined)[]>,
    'queryKey' | 'queryFn'
  >
} & (TVariables extends undefined
  ? {
      variables?: undefined
    }
  : O.RequiredKeys<NonNullable<TVariables>> extends never
  ? {
      variables?: TVariables
    }
  : {
      variables: TVariables
    })) {
  return useQuery(
    [queryKey, variables],
    async ({ signal }) => {
      const response = await fetch(getRequestUrl(queryKey, variables), {
        signal,
      })

      if (!response.ok) {
        throw new Error('Response error')
      }

      const json = (await response.json()) as TData
      return json
    },
    queryOptions
  )
}