swagger-typescript-api

interface User {
  id: number;
  name: string;
  email: string;
}

const getUser = async (id: number): Promise<User> => {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
};

# OpenAPI 3.0 예시 (일부)
paths:
  /users/{id}:
    get:
      summary: 사용자 조회
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name
        - email

npx swagger-typescript-api -p ./swagger.json -o ./src/api -n Api.ts

npx swagger-typescript-api -p http://localhost:3000/api-json -o ./src/api -n Api.ts

npm install --save-dev swagger-typescript-api

import * as path from "node:path";
import { generateApi } from "swagger-typescript-api";

await generateApi({
  name: "Api.ts",
  output: path.resolve(process.cwd(), "./src/__generated__"),
  url: "http://localhost:3000/api-json",
  httpClientType: "axios",  // 또는 "fetch"
  singleHttpClient: true,
  extractRequestParams: true,
  extractRequestBody: true,
});

// 생성된 코드
export interface User {
  /** @format int64 */
  id: number;
  name: string;
  email: string;
}

export interface CreateUserDto {
  name: string;
  email: string;
  /** @minLength 8 */
  password: string;
}

export interface PaginatedResponse {
  items: User[];
  total: number;
  page: number;
  limit: number;
}

// 생성된 HttpClient 클래스 (간략화)
export class HttpClient {
  private baseUrl: string;
  private securityData: SecurityDataType | null = null;

  constructor({ baseUrl, ...config }: ApiConfig) {
    this.baseUrl = baseUrl ?? "";
  }

  public setSecurityData(data: SecurityDataType | null) {
    this.securityData = data;
  }

  public request<T>({ path, method, body, query, ...params }: RequestParams): Promise<T> {
    // Fetch 또는 Axios를 사용한 실제 요청 로직
  }
}

export class Api extends HttpClient {
  users = {
    /**
     * @description 사용자 목록 조회
     * @name UsersList
     * @request GET:/users
     */
    usersList: (query?: { page?: number; limit?: number }) =>
      this.request<PaginatedResponse>({
        path: `/users`,
        method: "GET",
        query,
        format: "json",
      }),

    /**
     * @description 사용자 생성
     * @name UsersCreate
     * @request POST:/users
     */
    usersCreate: (data: CreateUserDto) =>
      this.request<User>({
        path: `/users`,
        method: "POST",
        body: data,
        type: ContentType.Json,
        format: "json",
      }),

    /**
     * @description 사용자 상세 조회
     * @name UsersDetail
     * @request GET:/users/{id}
     */
    usersDetail: (id: number) =>
      this.request<User>({
        path: `/users/${id}`,
        method: "GET",
        format: "json",
      }),
  };
}

const api = new Api({ baseUrl: "http://localhost:3000" });

// 타입 자동완성이 동작한다
const { data } = await api.users.usersList({ page: 1, limit: 10 });
// data의 타입은 PaginatedResponse

const newUser = await api.users.usersCreate({
  name: "홍길동",
  email: "hong@example.com",
  password: "12345678",
});
// newUser의 타입은 User

npx swagger-typescript-api -p ./swagger.json -o ./src/api --axios

src/api/
├── http-client.ts      # HttpClient 기본 클래스
├── data-contracts.ts   # 모든 타입 정의
├── Users.ts            # /users 관련 API 메서드
├── Products.ts         # /products 관련 API 메서드
└── Auth.ts             # /auth 관련 API 메서드

// 옵션 없이 생성된 코드
usersDetail: (id: number, query?: { fields?: string[] }) => ...

// --extract-request-params 적용 후
export interface UsersDetailParams {
  id: number;
  fields?: string[];
}
usersDetail: (params: UsersDetailParams) => ...

// 기본 (TypeScript enum)
export enum UserRole {
  Admin = "admin",
  User = "user",
  Guest = "guest",
}

// --union-enums 적용
export type UserRole = "admin" | "user" | "guest";

const httpClient = new HttpClient({
  baseUrl: "http://localhost:3000",
  securityWorker: (token) => ({
    headers: { Authorization: `Bearer ${token}` },
  }),
});

const api = new Api(httpClient);
api.setSecurityData(accessToken);

export namespace Users {
  export type UsersListRequestQuery = { page?: number; limit?: number };
  export type UsersListResponseBody = PaginatedResponse;
  export type UsersCreateRequestBody = CreateUserDto;
  export type UsersCreateResponseBody = User;
}

npx swagger-typescript-api \
  -p ./swagger.json \
  -o ./src/api \
  --templates ./api-templates

<%~ includeFile("@base/data-contracts.eta", it) %>

await generateApi({
  // ... 기본 설정
  hooks: {
    // 스키마가 파싱될 때
    onParseSchema: (originalSchema, parsedSchema) => {
      // 특정 스키마 이름 변경, 필드 추가/제거 등
      return parsedSchema;
    },
    
    // 라우트가 생성될 때
    onCreateRoute: (routeData) => {
      // 특정 엔드포인트 필터링, 이름 변경 등
      return routeData;
    },
    
    // 라우트 이름이 포맷될 때
    onFormatRouteName: (routeInfo, templateRouteName) => {
      // 기본 이름이 마음에 안 들면 변경
      return templateRouteName;
    },
    
    // 타입 이름이 포맷될 때
    onFormatTypeName: (typeName, rawTypeName) => {
      // 접두사/접미사 추가 등
      return typeName;
    },
  },
});

{
  "scripts": {
    "generate:api": "swagger-typescript-api -p http://localhost:3000/api-json -o ./src/api/__generated__ -n Api.ts --axios --union-enums --extract-request-params --single-http-client",
    "generate:api:local": "swagger-typescript-api -p ./swagger.json -o ./src/api/__generated__ -n Api.ts --axios --union-enums"
  }
}

// src/api/client.ts
import { Api } from "./__generated__/Api";

const api = new Api({
  baseUrl: import.meta.env.VITE_API_URL,
  securityWorker: (token: string | null) =>
    token ? { headers: { Authorization: `Bearer ${token}` } } : {},
});

export const setAuthToken = (token: string | null) => {
  api.setSecurityData(token);
};

export default api;

import api from "@/api/client";
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";

// 쿼리 키 팩토리
export const userKeys = {
  all: ["users"] as const,
  lists: () => [...userKeys.all, "list"] as const,
  list: (params: { page?: number }) => [...userKeys.lists(), params] as const,
  details: () => [...userKeys.all, "detail"] as const,
  detail: (id: number) => [...userKeys.details(), id] as const,
};

// 커스텀 훅
export const useUsers = (params: { page?: number; limit?: number }) =>
  useQuery({
    queryKey: userKeys.list(params),
    queryFn: () => api.users.usersList(params).then((r) => r.data),
  });

export const useUser = (id: number) =>
  useQuery({
    queryKey: userKeys.detail(id),
    queryFn: () => api.users.usersDetail(id).then((r) => r.data),
  });

export const useCreateUser = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: api.users.usersCreate,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    },
  });
};

# 방법 1: 생성 코드 무시 (CI에서 빌드 시 생성)
src/api/__generated__/

# 방법 2: 생성 코드 커밋 (변경 추적 가능)
# .gitignore에 추가하지 않음

GET  /api/fruits/getFruits
POST /api/fruits/addFruits  
GET  /api/vegetables/getVegetable

npx openapi-typescript ./swagger.json -o ./src/api/schema.d.ts

npx orval --input ./swagger.json --output ./src/api

# GitHub Actions 예시
- name: Generate API types
  run: npm run generate:api:local
  
- name: Check for uncommitted changes
  run: |
    git diff --exit-code src/api/__generated__/
    # 생성 코드가 커밋된 것과 다르면 실패