swagger-fsd-gen 1.0.0

package/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 swagger-client-autogen contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,205 @@
+# Swagger Client Autogen
+
+**ky + TanStack Query + FSD 패턴**을 위한 Swagger API 클라이언트 자동 생성 도구입니다.
+
+## ✨ 주요 기능
+
+- 🚀 **ky HTTP 클라이언트** 기반 API 클래스 자동 생성
+- 🔄 **TanStack Query** 훅 자동 생성 (useQuery, useMutation)
+- 📁 **FSD(Feature-Sliced Design)** 패턴 자동 적용
+- 🔐 **HTTP Basic Authentication** 지원
+- 📝 **TypeScript** 완전 지원 (타입 안전성)
+- 🎨 **Prettier** 자동 포맷팅
+
+## 📦 설치 방법
+
+### 1. 저장소 클론
+
+```bash
+git clone <repository-url>
+cd swagger-client-autogen
+```
+
+### 2. 의존성 설치
+
+```bash
+yarn install
+```
+
+### 3. 전역 설치 (선택사항)
+
+```bash
+yarn link
+```
+
+## 🚀 사용 방법
+
+### 1. Swagger 문서 다운로드
+
+```bash
+# 기본 사용법
+fetch-swagger --url https://api.example.com/swagger.json
+
+# 인증이 필요한 경우
+fetch-swagger --url https://api.example.com/swagger.json --username admin --password secret
+```
+
+**결과**: `swagger/` 디렉토리에 YAML 파일로 저장됩니다.
+
+### 2. API 클라이언트 생성
+
+```bash
+# 원격 Swagger 문서에서 생성
+generate-all --uri https://api.example.com/swagger.json
+
+# 로컬 파일에서 생성
+generate-all --uri ./swagger/my-api.yml
+
+# 인증이 필요한 경우
+generate-all --uri https://api.example.com/swagger.json --username admin --password secret
+
+# 커스텀 출력 경로 지정
+generate-all --uri ./swagger/my-api.yml \
+  --dto-output-path ./src/shared/api/dto.ts \
+  --api-output-path ./src/entities/{moduleName}/api/index.ts \
+  --query-output-path ./src/entities/{moduleName}/api/queries.ts \
+  --mutation-output-path ./src/entities/{moduleName}/api/mutations.ts
+```
+
+## 📁 생성되는 파일 구조 (FSD 패턴)
+
+```
+src/
+├── shared/
+│   └── api/
+│       └── dto.ts              # 모든 DTO 타입 정의
+└── entities/
+    └── {moduleName}/           # Swagger 태그별 모듈
+        └── api/
+            ├── index.ts        # API 클래스
+            ├── instance.ts     # API 인스턴스
+            ├── queries.ts      # TanStack Query 훅
+            └── mutations.ts    # TanStack Mutation 훅
+```
+
+## 💡 생성된 코드 사용 예시
+
+### 1. API 인스턴스 설정
+
+```typescript
+// src/app/providers/api.ts
+import ky from "ky";
+
+export const apiInstance = ky.create({
+  prefixUrl: "https://api.example.com",
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+```
+
+### 2. API 클래스 사용
+
+```typescript
+// src/entities/user/api/instance.ts (자동 생성됨)
+import { UserApi } from "./index";
+import { apiInstance } from "@/app/providers/api";
+
+export const userApi = new UserApi(apiInstance);
+```
+
+### 3. TanStack Query 훅 사용
+
+```typescript
+// src/pages/user/ui/UserProfile.tsx
+import { useGetUserByIdQuery } from "@/entities/user/api/queries";
+import { useUpdateUserMutation } from "@/entities/user/api/mutations";
+
+export const UserProfile = ({ userId }: { userId: number }) => {
+  // Query 사용
+  const { data: user, isLoading } = useGetUserByIdQuery(userId);
+
+  // Mutation 사용
+  const updateUserMutation = useUpdateUserMutation({
+    onSuccess: () => {
+      console.log("User updated successfully!");
+    },
+  });
+
+  const handleUpdate = (userData: UpdateUserRequestDto) => {
+    updateUserMutation.mutate({
+      id: userId,
+      body: userData,
+    });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{user?.name}</h1>
+      <button onClick={() => handleUpdate({ name: "New Name" })}>
+        Update User
+      </button>
+    </div>
+  );
+};
+```
+
+## ⚙️ 설정 옵션
+
+### 명령행 옵션
+
+| 옵션                     | 단축키 | 설명                            | 기본값                                       |
+| ------------------------ | ------ | ------------------------------- | -------------------------------------------- |
+| `--uri`                  | `-u`   | Swagger 문서 URL 또는 파일 경로 | 필수                                         |
+| `--username`             | `-un`  | HTTP Basic Auth 사용자명        | -                                            |
+| `--password`             | `-pw`  | HTTP Basic Auth 비밀번호        | -                                            |
+| `--dto-output-path`      | `-dp`  | DTO 파일 출력 경로              | `src/shared/api/dto.ts`                      |
+| `--api-output-path`      | `-ap`  | API 클래스 출력 경로            | `src/entities/{moduleName}/api/index.ts`     |
+| `--query-output-path`    | `-qp`  | Query 훅 출력 경로              | `src/entities/{moduleName}/api/queries.ts`   |
+| `--mutation-output-path` | `-mp`  | Mutation 훅 출력 경로           | `src/entities/{moduleName}/api/mutations.ts` |
+| `--project-template`     | `-pt`  | 커스텀 템플릿 경로              | -                                            |
+
+### 경로에서 `{moduleName}` 사용
+
+`{moduleName}`을 포함한 경로는 Swagger 태그명으로 자동 대체됩니다.
+
+예: `User` 태그 → `user` 모듈명으로 변환
+
+## 🔧 커스텀 템플릿
+
+기본 템플릿을 복사하여 프로젝트에 맞게 수정할 수 있습니다:
+
+```bash
+# 템플릿 복사
+cp -r templates/ ./my-templates/
+
+# 커스텀 템플릿 사용
+generate-all --uri ./swagger/my-api.yml --project-template ./my-templates/
+```
+
+## 🛠️ 개발 환경
+
+- **Node.js**: 18+
+- **Package Manager**: Yarn 4.7.0
+- **Type**: ES Module
+
+## 📋 의존성
+
+- `swagger-typescript-api`: Swagger 문서 파싱 및 코드 생성
+- `minimist`: 명령행 인수 파싱
+- `js-yaml`: YAML 파일 처리
+- `node-fetch`: HTTP 요청
+
+## 🤝 기여하기
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 라이선스
+
+이 프로젝트는 [MIT License](LICENSE) 하에 배포됩니다.

package/USAGE.md

@@ -0,0 +1,137 @@
+# 🚀 Quick Start Guide
+
+## 📋 요구사항
+
+- Node.js 18+
+- Yarn 4.7.0+
+
+## 🔧 설치
+
+```bash
+# 1. 저장소 클론
+git clone <your-repo-url>
+cd swagger-client-autogen
+
+# 2. 의존성 설치
+yarn install
+
+# 3. 전역 설치 (선택사항)
+yarn link
+```
+
+## 💡 사용법
+
+### 1단계: Swagger 문서 다운로드 (선택사항)
+
+```bash
+# 원격 Swagger 문서를 로컬에 저장
+fetch-swagger --url https://api.example.com/swagger.json
+
+# 인증이 필요한 경우
+fetch-swagger --url https://api.example.com/swagger.json --username admin --password secret
+```
+
+### 2단계: API 클라이언트 생성
+
+```bash
+# 원격 URL에서 직접 생성
+generate-all --uri https://api.example.com/swagger.json
+
+# 로컬 파일에서 생성
+generate-all --uri ./swagger/my-api.yml
+
+# 인증이 필요한 경우
+generate-all --uri https://api.example.com/swagger.json --username admin --password secret
+```
+
+## 📁 생성되는 파일
+
+```
+src/
+├── shared/
+│   └── api/
+│       └── dto.ts              # 모든 DTO 타입
+└── entities/
+    └── {moduleName}/           # 각 Swagger 태그별
+        └── api/
+            ├── index.ts        # API 클래스
+            ├── instance.ts     # API 인스턴스
+            ├── queries.ts      # Query 훅
+            └── mutations.ts    # Mutation 훅
+```
+
+## 🎯 프로젝트에 적용하기
+
+### 1. 필요한 패키지 설치
+
+```bash
+npm install ky @tanstack/react-query
+```
+
+### 2. API 인스턴스 설정
+
+```typescript
+// src/app/providers/api.ts
+import ky from "ky";
+
+export const apiInstance = ky.create({
+  prefixUrl: "https://api.example.com",
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+```
+
+### 3. 생성된 코드 사용
+
+```typescript
+// Query 사용
+import { useGetUsersQuery } from "@/entities/user/api/queries";
+
+const { data: users, isLoading } = useGetUsersQuery();
+
+// Mutation 사용
+import { useCreateUserMutation } from "@/entities/user/api/mutations";
+
+const createUser = useCreateUserMutation({
+  onSuccess: () => console.log("User created!"),
+});
+
+createUser.mutate({ body: { name: "John" } });
+```
+
+## ⚙️ 커스텀 설정
+
+```bash
+# 출력 경로 커스터마이징
+generate-all --uri ./swagger.json \
+  --dto-output-path ./src/types/api.ts \
+  --api-output-path ./src/api/{moduleName}/client.ts \
+  --query-output-path ./src/api/{moduleName}/queries.ts \
+  --mutation-output-path ./src/api/{moduleName}/mutations.ts
+
+# 커스텀 템플릿 사용
+generate-all --uri ./swagger.json --project-template ./my-templates/
+```
+
+## 🔍 문제 해결
+
+### 의존성 오류
+
+```bash
+yarn install
+```
+
+### 권한 오류 (전역 설치 시)
+
+```bash
+yarn unlink
+yarn link
+```
+
+### 생성된 파일 확인
+
+```bash
+# 생성된 파일 목록 확인
+find src -name "*.ts" -type f | grep -E "(api|dto)" | sort
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "swagger-fsd-gen",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "swagger",
+    "openapi",
+    "api-client",
+    "typescript",
+    "ky",
+    "tanstack-query",
+    "code-generator",
+    "fsd"
+  ],
+  "author": "sen2y",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "fetch-swagger": "./scripts/fetch-swagger.js",
+    "generate-all": "./scripts/generate-all.js"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "minimist": "^1.2.8",
+    "node-fetch": "^3.3.2",
+    "swagger-typescript-api": "^13.0.22"
+  },
+  "packageManager": "yarn@4.7.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sen-jik/swagger-autogen.git"
+  },
+  "homepage": "https://github.com/sen-jik/swagger-autogen#readme",
+  "bugs": {
+    "url": "https://github.com/sen-jik/swagger-autogen/issues"
+  }
+}

package/scripts/fetch-swagger.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+/**
+ * Swagger 문서 다운로드 도구
+ * - 원격 Swagger 문서를 가져와서 로컬에 YAML 파일로 저장
+ * - HTTP Basic Authentication 지원
+ * - 파일명은 Swagger 문서의 title을 kebab-case로 변환하여 생성
+ */
+
+import path from "node:path";
+import minimist from "minimist";
+import yaml from "js-yaml";
+import { fetchSwagger } from "../utils/fetch-swagger.js";
+import { toKebabCase } from "../utils/string.js";
+import { writeFileToPath } from "../utils/file.js";
+
+/**
+ * 명령행 인수 파싱
+ */
+const argv = minimist(process.argv.slice(2), {
+  string: ["url", "username", "password"],
+  alias: {
+    u: "url",
+    un: "username",
+    pw: "password",
+  },
+});
+
+const { url, username, password } = argv;
+
+/**
+ * 사용법 출력
+ */
+const printUsage = () => {
+  console.error("❗️ Error: Please provide the Swagger URL");
+  console.error(
+    "Usage: fetch-swagger --url <swagger-url> [--username <username>] [--password <password>]"
+  );
+  console.error("\nExamples:");
+  console.error("  fetch-swagger --url https://api.example.com/swagger.json");
+  console.error(
+    "  fetch-swagger --url https://api.example.com/swagger.json --username admin --password secret"
+  );
+};
+
+/**
+ * 메인 실행 함수
+ */
+const main = async () => {
+  console.log("📥 Starting Swagger document download...\n");
+
+  // URL 필수 체크
+  if (!url) {
+    printUsage();
+    process.exit(1);
+  }
+
+  try {
+    console.log(`🔄 Fetching Swagger document from: ${url}`);
+
+    // 인증 정보가 있는 경우 표시
+    if (username) {
+      console.log(`🔐 Using authentication: ${username}`);
+    }
+
+    // Swagger 문서 가져오기
+    const swaggerData = await fetchSwagger(url, username, password);
+
+    // YAML 형식으로 변환
+    const yamlData = yaml.dump(swaggerData);
+
+    // 파일명 생성 (title을 kebab-case로 변환)
+    const fileName = toKebabCase(swaggerData.info.title);
+    const outputPath = path.resolve(process.cwd(), `swagger/${fileName}.yml`);
+
+    // 파일 저장
+    await writeFileToPath(outputPath, yamlData);
+
+    console.log(`✅ Successfully downloaded and saved Swagger document`);
+    console.log(`📁 File saved to: swagger/${fileName}.yml`);
+    console.log(`📋 API Title: ${swaggerData.info.title}`);
+    console.log(`📝 API Version: ${swaggerData.info.version}`);
+  } catch (error) {
+    console.error("\n❌ Failed to download Swagger document:");
+    console.error(error.message);
+    process.exit(1);
+  }
+};
+
+main();