OpenAPI & Service Generator
สคริปต์ Node ที่เลือกได้ซึ่งจัดเตรียมแยกจาก Core HTTP client ใช้เฉพาะเมื่อสร้าง TypeScript type และ service file จาก OpenAPI/Swagger JSON เท่านั้น
ฟังก์ชันเลือก: ไม่จำเป็นต้องใช้กับ Core
ผู้ใช้ทั่วไปของ @byeolnaerim/typed-rx-http, /next หรือ /rsocket ไม่จำเป็นต้องรันสคริปต์นี้และไม่จำเป็นต้องติดตั้ง openapi-typescript ในโปรเจกต์
การแยกการพึ่งพา openapi-typescript
การสร้าง OpenAPI type ต้องการ openapi-typescript CLI แต่แพ็คเกจจะไม่ใส่ไว้ใน dependencies ทั่วไป typed-rx-http เองมี devDependencies.typescript ที่รักษามาตรฐาน TypeScript 6.0.3 และใช้สภาพแวดล้อม npx ชั่วคราวเฉพาะใน OpenAPI auto node script เท่านั้น
ในขั้นตอนการสร้าง OpenAPI พื้นฐานจะรัน openapi-typescript และ [email protected] พร้อมกัน ดังนั้นจึงไม่เปลี่ยนแปลงหรือใช้เวอร์ชัน TypeScript/openapi-typescript ที่ติดตั้งในโปรเจกต์ของผู้ใช้
หากจำเป็นสามารถล็อคคำสั่งทั้งหมดไว้ที่ openApiTypescriptCommand ได้
หรือสามารถเปลี่ยนเฉพาะเวอร์ชันแพ็คเกจที่กำหนดคำสั่งพื้นฐานได้
ก่อนอื่น: เตรียมไฟล์โปรเจกต์ที่ commonServiceFile จะชี้ไปยัง
ต้องเข้าใจก่อนว่า commonServiceFile จะปรากฏในตัวอย่าง generator ไฟล์นี้ไม่ใช่ตัวเลือกในการสร้างไฟล์ แต่เป็นเส้นทางของไฟล์ที่เจ้าของโปรเจกต์นำเข้า HTTP ฟังก์ชันทั่วไป ไฟล์สามารถตั้งชื่อได้ตามต้องการ เช่น rxjsHttpService.ts, commonService.ts เป็นต้น
โค้ดทั้งหมดในรูปแบบที่เสร็จสมบูรณ์ขั้นต่ำ
ไฟล์ด้านล่างสร้าง createHttpClient ขึ้นมาในโปรเจกต์เพียงครั้งเดียวและ export ให้ generated service ใช้ callApi และ callApiStream หากไม่ต้องการ cache หรือ session auth สามารถเริ่มต้นจากโครงสร้างนี้ได้
rxjsHttpService.ts
tsโค้ดทั้งหมดรวมถึง Session/CSR/SSR cache
หาก generated service ใช้ callApiClientCache หรือ callApiServerCache หรือหากต้องการจัดการ header และการรับรองความถูกต้องของเซสชันใน Next.js ให้ขยายเป็นรูปแบบทั้งหมดต่อไปนี้
rxjsHttpService.ts
tsวิธีการรัน
ไฟล์ที่สร้างขึ้น
การตั้งค่าเริ่มต้นจะสร้างไฟล์ด้านล่างนี้
apiUnionArrays.tsสร้าง readonly คอนสแตนต์อาร์เรย์สำหรับ enum ของ OpenAPI schema ไม่เพียงแต่ยังรวมถึง query, path, header, cookie parameter enum และจัดการ items.enum ของอาร์เรย์ query parameter ด้วย
เลือก: เชื่อมต่อ Swagger ของ backend กับ commonService ของโปรเจกต์
ตั้งแต่ที่นี่เป็นตัวอย่างการเชื่อมต่อ generator กับโปรเจกต์จริง WebFlux/webflux-fe-dev-assistant เป็นเพียงวิธีหนึ่งในการให้ Swagger ไม่ใช่การพึ่งพาที่จำเป็น
เตรียมเอกสาร Swagger
Swagger สามารถเป็น Springdoc, เครื่องมือ OpenAPI อื่น ๆ หรือไฟล์ที่เขียนขึ้นเอง หากใช้ WebFlux functional endpoint webflux-fe-dev-assistantสามารถใช้วิธีการให้เอกสาร Swagger ได้เช่นกัน
ตัวอย่างการสร้างที่ระบุทางเลือกในโปรเจกต์
สามารถระบุ endpoint ของ backend, swagger.json ที่จะเก็บ, เส้นทางการส่งออก type/service และ commonServiceFile ให้เหมาะสมกับโครงสร้างโปรเจกต์ได้
generateSwagger.cjs
jsในสภาพแวดล้อมที่ไม่สามารถรับเอกสารผ่าน HTTP ได้ สามารถใช้ร่วมกับตัวเลือกการส่งออกเดียวกันได้ generateSwaggerFromFileสามารถใช้ได้
commonServiceFile คือเส้นทางที่นำเข้า
commonServiceFile.เป็นเส้นทางของไฟล์ที่เจ้าของโปรเจกต์นำเข้า callApi, callApiStream และ cache wrapper ไฟล์นี้ไม่ใช่ตัวเลือกในการสร้างหรือเขียนทับโดย generator
ApiBusinessService.ts
tsตัวอย่างการจัดวางผลลัพธ์ที่สร้างในโปรเจกต์
ไฟล์สาธารณะที่กำหนดโดย commonServiceFile เช่น rxjsHttpService.ts จะถูกจัดการโดยโปรเจกต์โดยตรง ผลลัพธ์ภายใต้ auto และ @types/auto จะถูกสร้างใหม่เมื่อเอกสารเปลี่ยนแปลง
กฎการตั้งชื่อไฟล์และฟังก์ชัน
ชื่อไฟล์บริการจะถูกกำหนดจากสอง segment แรกของ URL และชื่อฟังก์ชันจะถูกกำหนดจาก segment ที่สามขึ้นไป ตัวแปร path จะรวมอยู่ในชื่อฟังก์ชันในรูปแบบ By + PascalCase
GET /api/business/workplaces/search
ApiBusinessService.ts → workplacesSearch({ params })
GET /api/business/workplaces/{id}
ApiBusinessService.ts → workplacesById({ path })
GET /api/orders/history/search
ApiOrdersService.ts → historySearch({ params })
POST /oauth2/login
Oauth2LoginService.ts → post({ body })
พารามิเตอร์ที่เรียกใช้ฟังก์ชันสร้าง
GeneratedServiceUsage.tsx
tsxคีย์พารามิเตอร์ query ของ service ที่สร้างขึ้นคือ params, ตัวแปร path คือ path, request body คือ body จะถูกแปลงเป็น ServiceArguments ของ queryString, pathVariable, body ภายในฟังก์ชันสร้าง