OpenAPI & Service Generator

일반적인 @byeolnaerim/typed-rx-http, /next 또는 /rsocket 사용자는 이 script를 실행하지 않아도 되고 openapi-typescript를 프로젝트에 설치할 필요도 없습니다.

OpenAPI 타입 생성에는 openapi-typescript CLI가 필요하지만, 패키지는 이를 일반 dependencies에 넣지 않습니다. typed-rx-http 자체의 devDependencies.typescript는 TypeScript 6.0.3 기준을 유지하고, OpenAPI auto node script에서만 별도의 npx 임시 환경을 사용합니다.

기본 OpenAPI 생성 단계에서는 openapi-typescript와 [email protected]을 함께 실행하므로 사용자의 프로젝트에 설치된 TypeScript/openapi-typescript 버전을 바꾸거나 사용하지 않습니다.

필요하면 전체 명령을 openApiTypescriptCommand로 고정할 수 있습니다.

또는 기본 명령을 구성하는 package version만 바꿀 수도 있습니다.

generator 예제에 commonServiceFile이 등장하기 전에 이 파일부터 이해해야 합니다. commonServiceFile은 파일을 만들어 주는 옵션이 아니라 generated service가 공통 HTTP 함수들을 import할 프로젝트 소유 파일의 경로입니다. 파일명은 rxjsHttpService.ts, commonService.ts 등 자유롭게 정할 수 있습니다.

최소 완성형 전체 코드

아래 파일은 createHttpClient를 프로젝트에서 한 번 생성하고 callApi와 callApiStream을 generated service가 재사용하도록 export합니다. cache나 session auth가 필요하지 않다면 이 구조부터 시작할 수 있습니다.

Session/CSR/SSR cache까지 포함한 전체 코드

generated service가 callApiClientCache 또는 callApiServerCache까지 사용하거나 Next.js에서 요청별 header와 세션 인증을 공통 처리하려면 다음 전체 형태로 확장합니다.

기본 설정은 아래 파일들을 생성합니다.

apiUnionArrays.ts는 OpenAPI schema enum뿐 아니라 query, path, header, cookie parameter enum의 readonly 상수 배열도 생성하고, 배열 query parameter의 items.enum도 처리합니다.

Swagger는 Springdoc, 다른 OpenAPI 도구 또는 직접 작성한 파일이어도 됩니다. WebFlux functional endpoint를 사용한다면 webflux-fe-dev-assistant로 Swagger 문서를 제공하는 방식도 사용할 수 있습니다.

백엔드 endpoint, 저장할 swagger.json, 타입/service 출력 경로와 commonServiceFile을 프로젝트 구조에 맞게 명시할 수 있습니다.

HTTP로 문서를 받을 수 없는 환경에서는 같은 출력 옵션과 함께 generateSwaggerFromFile을 사용할 수 있습니다.

commonServiceFile은 생성된 service가 callApi, callApiStream과 cache wrapper를 import할 프로젝트 소유 파일의 경로입니다. generator가 이 파일을 생성하거나 덮어쓰는 옵션이 아닙니다.

rxjsHttpService.ts처럼 commonServiceFile로 지정한 공용 파일은 프로젝트가 직접 관리합니다. auto와 @types/auto 아래 결과는 문서가 바뀌면 다시 생성됩니다.

서비스 파일명은 URL의 앞 두 segment로, 함수명은 세 번째 이후 segment로 결정됩니다. path variable은 By + PascalCase 형태로 함수명에 포함됩니다.

생성된 service의 query parameter key는 params, path variable은 path, request body는 body입니다. 생성 함수 내부에서 각각 queryString, pathVariable, body의 ServiceArguments로 변환됩니다.