OAS (Open API Spec)

// package.json
{
  ...
  "scripts" : {
    "openapi": openapi-generator-cli generate -g typescript-axios -i 타겟 OAS 경로 -o 생성한 코드를 저장할 경로
  }
}

npx create-next-app@latest oas-test
npm i -D @openapitools/openapi-generator-cli -g

// openapitools.json
{
  // OpenAPI Generator CLI 구성 스키마 정의
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  
  // JSON 파일의 들여쓰기 공백 수
  "spaces": 2,
  
  "generator-cli": {
    // OpenAPI Generator CLI 버전
    "version": "5.3.1"
  },
  
  // ES6 문법 지원 여부
  "supportsES6": true,
  
  // API와 모델을 별도의 파일로 생성할지 여부
  "withSeparateModelsAndApi": true,
  
  // 생성된 API 클래스가 위치할 패키지명
  "apiPackage": "api",
  
  // 생성된 모델 클래스가 위치할 패키지명
  "modelPackage": "models",
  
  // enum 프로퍼티의 명명 규칙 (원본 유지)
  "enumPropertyNaming": "original",
  
  // enum 이름에 추가할 접미사 (없음)
  "enumNameSuffix": "",
  
  // API 호출 시 단일 객체 파라미터 사용 여부
  "useSingleRequestParameter": false,
  
  // TypeScript 3.0 이상의 기능 사용 여부
  "typescriptThreePlus": true
}

// package.json
{
  ...
  "scripts" : {
    "openapi": "curl https://petstore3.swagger.io/api/v3/openapi.json > ./src/api/target-api.json && openapi-generator-cli generate -g typescript-axios -i ./src/api/target-api.json -o ./src/api/openapi -c ./openapitools.json"
  }
}
 

npm run openapi

{
  Options:
  -v, --version: 현재 버전 출력
  -p, --path <string>: swagger 스키마의 경로 또는 URL
  -o, --output <string>: TypeScript API 파일의 출력 경로 (기본값: "./")
  -n, --name <string>: 출력 TypeScript API 파일의 이름 (기본값: "Api.ts")
  -t, --templates <string>: 템플릿이 포함된 폴더의 경로
  -d, --default-as-success: "default" 응답 상태 코드를 성공 응답으로 사용
                            일부 swagger 스키마는 기본적으로 "default" 응답 상태 코드를 성공 응답 타입으로 사용합니다. (기본값: false)
  -r, --responses: 요청 응답에 대한 추가 정보 생성
                    잘못된 응답에 대한 타이핑도 추가 (기본값: false)
  --union-enums: 모든 "enum" 타입을 유니온 타입 (T1 | T2 | TN)으로 생성 (기본값: false)
  --add-readonly: readonly 속성 생성 (기본값: false)
  --route-types: API 경로에 대한 타입 정의 생성 (기본값: false)
  --no-client: API 클래스를 생성하지 않음
  --enum-names-as-values: 'x-enumNames'의 값을 enum 값으로 사용 (키로만 사용하지 않음) (기본값: false)
  --extract-request-params: 요청 매개변수를 데이터 계약으로 추출 (경로 매개변수와 쿼리 매개변수를 하나의 객체로 결합)
  --extract-request-body: 요청 본문 타입을 데이터 계약으로 추출 (기본값: false)
  --extract-response-body: 응답 본문 타입을 데이터 계약으로 추출 (기본값: false)
  --extract-response-error: 응답 오류 타입을 데이터 계약으로 추출 (기본값: false)
  --modular: HTTP 클라이언트, data-contracts 및 경로에 대해 별도의 파일 생성 (기본값: false)
  --js: 선언 파일이 있는 JS API 모듈 생성 (기본값: false)
  --module-name-index <number>: 경로 분리를 위해 사용할 경로 인덱스 결정 (예: GET:/fruits/getFruit -> index:0 -> moduleName -> fruits) (기본값: 0)
  --module-name-first-tag: 첫 번째 태그를 기준으로 경로 분리 (기본값: false)
  --disableStrictSSL: 엄격한 SSL 비활성화 (기본값: false)
  --disableProxy: 프록시 비활성화 (기본값: false)
  --axios: axios HTTP 클라이언트 생성 (기본값: false)
  --unwrap-response-data: 응답에서 데이터 항목 풀기 (기본값: false)
  --disable-throw-on-error: response.ok가 true가 아니더라도 오류를 발생시키지 않음 (기본값: false)
  --single-http-client: Api 생성자에 HttpClient 인스턴스를 전달할 수 있음 (기본값: false)
  --silent: 콘솔에 오류만 출력 (기본값: false)
  --default-response <type>: 빈 응답 스키마에 대한 기본 타입 (기본값: "void")
  --type-prefix <string>: 데이터 계약 이름 접두사 (기본값: "")
  --type-suffix <string>: 데이터 계약 이름 접미사 (기본값: "")
  --clean-output: API 생성 전에 출력 폴더를 정리합니다. 경고: 데이터 손실이 발생할 수 있음 (기본값: false)
  --api-class-name <string>: API 클래스의 이름 (기본값: "Api")
  --patch: swagger 소스 정의의 작은 오류 수정 (기본값: false)
  --debug: 이 도구 내부의 프로세스에 대한 추가 정보 (기본값: false)
  --another-array-type: Array<Type>으로 배열 타입 생성 (기본적으로 Type[]) (기본값: false)
  --sort-types: 필드 및 타입 정렬 (기본값: false)
  --sort-routes: 경로를 알파벳 순으로 정렬 (기본값: false)
  --custom-config <string>: 사용자 정의 구성: primitiveTypeConstructs, hooks, 등 (기본값: "")
  --extract-enums: 인라인 인터페이스/타입 콘텐츠에서 모든 열거형을 추출하여 TypeScript 열거형 구조로 생성 (기본값: false)
  -h, --help: 명령어 도움말 표시
 
Commands:
  generate-templates: ".ejs" 템플릿 생성에 필요
    -o, --output <string>: 생성된 템플릿의 출력 경로
    -m, --modular: HTTP 클라이언트, data-contracts 및 경로에 대해 별도의 파일로 템플릿 생성 (기본값: false)
    --http-client <string>: HTTP 클라이언트 유형 (가능한 값: "fetch", "axios") (기본값: "fetch")
    -c, --clean-output: 템플릿 생성 전에 출력 폴더를 정리합니다. 경고: 데이터 손실이 발생할 수 있음 (기본값: false)
    -r, --rewrite: 기존 템플릿의 내용을 덮어씀 (기본값: false)
    --silent: 콘솔에 오류만 출력 (기본값: false)
    -h, --help: 명령어 도움말 표시
}

npm i -D swagger-typescript-api -g

// package.json
{
  "scripts": {
    "openapi": "swagger-typescript-api - 옵션 -p OAS 파일 경로 -o 실행 결과 저장 경로"
  }
}

npm run openapi