OpenAPI & Trình tạo Service
Script Node tùy chọn được cung cấp riêng biệt với Core HTTP client. Chỉ sử dụng khi tạo kiểu TypeScript và tệp dịch vụ từ OpenAPI/Swagger JSON.
Tính năng tùy chọn: Không cần thiết cho việc sử dụng Core
Người dùng thông thường của @byeolnaerim/typed-rx-http, /next hoặc /rsocket không cần phải chạy script này và không cần cài đặt openapi-typescript vào dự án.
Cách ly phụ thuộc openapi-typescript
Việc tạo kiểu OpenAPI cần CLI openapi-typescript, nhưng gói không đưa vào dependencies thông thường. devDependencies.typescript của typed-rx-http duy trì tiêu chuẩn TypeScript 6.0.3, và chỉ sử dụng môi trường tạm thời npx riêng trong script node tự động OpenAPI.
Trong giai đoạn tạo OpenAPI cơ bản, openapi-typescript và [email protected] được chạy cùng nhau, vì vậy không thay đổi hoặc không sử dụng phiên bản TypeScript/openapi-typescript đã cài đặt trong dự án của người dùng.
Nếu cần, có thể cố định toàn bộ lệnh bằng openApiTypescriptCommand.
Hoặc chỉ cần thay đổi phiên bản gói cấu thành lệnh cơ bản.
Trước tiên: Chuẩn bị tệp dự án mà commonServiceFile sẽ chỉ đến
Trước khi commonServiceFile xuất hiện trong ví dụ generator, bạn cần hiểu tệp này trước. commonServiceFile không phải là tùy chọn tạo tệp mà là đường dẫn đến tệp sở hữu dự án mà dịch vụ được tạo sẽ nhập các hàm HTTP chung. Tên tệp có thể được đặt tự do như rxjsHttpService.ts, commonService.ts, v.v.
Mã hoàn chỉnh kiểu tối thiểu
Tệp dưới đây tạo một lần createHttpClient trong dự án và export callApi và callApiStream để dịch vụ được tạo tái sử dụng. Nếu không cần bộ nhớ đệm hoặc xác thực phiên, bạn có thể bắt đầu từ cấu trúc này.
rxjsHttpService.ts
tsMã hoàn chỉnh bao gồm bộ nhớ đệm Session/CSR/SSR
Nếu dịch vụ được tạo sử dụng callApiClientCache hoặc callApiServerCache hoặc muốn xử lý chung header theo yêu cầu và xác thực phiên trong Next.js, hãy mở rộng theo hình thức toàn bộ sau.
rxjsHttpService.ts
tsCách thực thi
Tệp được tạo ra
Cấu hình mặc định sẽ tạo ra các tệp dưới đây.
apiUnionArrays.tsTạo không chỉ enum schema OpenAPI mà còn cả mảng hằng readonly cho enum tham số query, path, header, cookie, và cũng xử lý items.enum của tham số query.
Tùy chọn: Kết nối Swagger backend với commonService của dự án
Từ đây là ví dụ kết nối generator với dự án thực tế. WebFlux/webflux-fe-dev-assistant chỉ là một trong những cách cung cấp Swagger và không phải là phụ thuộc bắt buộc.
Chuẩn bị tài liệu Swagger
Swagger có thể là Springdoc, các công cụ OpenAPI khác hoặc tệp tự viết. Nếu bạn sử dụng endpoint functional WebFlux, webflux-fe-dev-assistantCũng có thể sử dụng cách cung cấp tài liệu Swagger.
Ví dụ về việc tạo ra với tùy chọn được chỉ định trong dự án
Có thể chỉ định endpoint backend, swagger.json sẽ lưu, đường dẫn xuất kiểu/dịch vụ và commonServiceFile theo cấu trúc dự án.
generateSwagger.cjs
jsTrong môi trường không thể nhận tài liệu qua HTTP, có thể sử dụng cùng tùy chọn xuất như vậy. generateSwaggerFromFileCó thể sử dụng.
commonServiceFile là đường dẫn đến tệp nhập
commonServiceFileLà đường dẫn đến tệp sở hữu dự án mà dịch vụ được tạo sẽ nhập callApi, callApiStream và wrapper bộ nhớ đệm. Generator không có tùy chọn tạo hoặc ghi đè tệp này.
ApiBusinessService.ts
tsVí dụ về kết quả tạo ra trong dự án
Tệp công cộng được chỉ định bằng commonServiceFile như rxjsHttpService.ts sẽ được dự án quản lý trực tiếp. Kết quả dưới auto và @types/auto sẽ được tạo lại khi tài liệu thay đổi.
Quy tắc tên tệp và tên hàm
Tên tệp dịch vụ được quyết định bởi hai segment đầu tiên của URL, tên hàm được quyết định từ segment thứ ba trở đi. Biến đường dẫn được bao gồm trong tên hàm theo dạng 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 })
Tham số gọi hàm tạo
GeneratedServiceUsage.tsx
tsxKhóa tham số query của dịch vụ được tạo là params, biến đường dẫn là path, và body yêu cầu là body. Trong hàm tạo, chúng sẽ được chuyển đổi thành ServiceArguments cho queryString, pathVariable, body.