Tự động tạo OpenAPI 3.0.0 từ
Mã nguồn làm căn cứ duy nhất
Hỗ trợ NestJS và Next.js App Router trên cùng lõi TypeScript, kết hợp phân tích tĩnh Rust với khả năng cấu trúc dữ liệu của ChatGPT. Mã nguồn là nguồn tin cậy duy nhất — không tự tạo điểm cuối, DTO, trường dữ liệu hoặc mã trạng thái khi không có căn cứ từ mã nguồn.
Quy trình chuẩn hóa
9 bước vận hành tự động và an toàn
Từ dự án NestJS hoặc Next.js App Router cục bộ đến OpenAPI 3.0.0 theo cùng một quy trình.
-
•
Mở dự án: Chọn dự án TypeScript có
package.json; NestJS thường dùngsrc/, Next.js App Router dùngapp/hoặcsrc/app/. - • Phân tích AST: Nhấn Tạo ngữ cảnh Swagger. Dịch vụ quét một lần, nhận diện khung ứng dụng rồi chuyển xử lý sang bộ điều hợp NestJS hoặc Next.js.
- • Đánh giá trạng thái: Kiểm tra trạng thái Sẵn sàng, Warning hoặc Incomplete.
- • Sao chép câu lệnh chuẩn: Lấy nội dung yêu cầu kỹ thuật với các ràng buộc nghiêm ngặt.
- • Gửi tới ChatGPT: ChatGPT chuyển cấu trúc đã trích xuất thành JSON OpenAPI 3.0.0.
- • Dán JSON vào ứng dụng: Đưa kết quả trở lại ứng dụng để kiểm tra tính hợp lệ.
- • Kiểm tra trên máy: Kiểm tra cú pháp, tham chiếu schema bằng $ref và các trường bắt buộc.
- • Xem trước: Hiển thị JSON đã định dạng để dễ rà soát.
- • Xuất `openapi.json`: Lưu an toàn trong thư mục dự án và chỉ ghi đè khi được cho phép.
Trực quan hóa
Mô phỏng luồng dữ liệu tương tác
Chuyển giữa NestJS và Next.js để xem cùng một quy trình chuyển mã nguồn đặc thù của từng khung ứng dụng thành OpenAPI 3.0.0.
Kiến trúc lõi tách biệt: tốc độ của Rust, an toàn về kiểu dữ liệu
Lõi TypeScript dùng chung giữ mô hình dữ liệu trung lập với khung ứng dụng. NestJS và Next.js App Router có bộ điều hợp riêng cho quy tắc định tuyến và hàm xử lý; FastAPI vẫn là bộ điều hợp dự kiến trong tương lai; logic Python không được đưa vào lõi hiện tại.
route.ts trong Next.js.../) và bắt buộc xác nhận checkbox ghi đè nếu openapi.json đã tồn tại.├── extractor.rs # Lõi: AST TypeScript và metadata schema
├── resolver.rs # Lõi: import/tái xuất và phân giải kiểu
├── model.rs # Mô hình Swagger trung lập với khung ứng dụng
├── scanner.rs # Quét mã nguồn dự án
├── service.rs # Nhận diện khung ứng dụng và chuyển bộ điều hợp
├── validator.rs # Kiểm tra OpenAPI và xuất tệp an toàn
└── frameworks/
├── nestjs/ # Bộ điều hợp Controller/decorator
│ ├── extractor.rs
│ ├── validation.rs # class-validator
│ ├── resolver.rs
│ └── response_flow.rs
└── nextjs/ # Bộ điều hợp route.ts của App Router
├── extractor.rs # Hàm HTTP export, Request/Response
└── resolver.rs # Tái sử dụng bộ phân giải kiểu của lõiĐặc tả kỹ thuật
Khả năng nhận diện và ánh xạ tự động
NestJS dùng decorator và class-validator; Next.js App Router dùng cấu trúc route theo hệ thống tệp, hàm xử lý được khai báo bằng `export` và dữ liệu từ Request/Response làm căn cứ.
NestJS: `class-validator` → schema
| Decorator | Quy tắc OpenAPI 3.0.0 |
|---|---|
| @IsString() | type: "string" |
| @IsInt() / @IsNumber() | type: "integer" / "number" |
| @IsEmail() | format: "email" |
| @IsUUID() | format: "uuid" |
| @Min(val) / @Max(val) | minimum: val, maximum: val |
| @MinLength() / @MaxLength() | minLength: n, maxLength: n |
| @IsEnum(Role) | enum: ["ADMIN", "USER"] |
| @IsOptional() | Loại khỏi danh sách required |
Mã trạng thái HTTP theo khung ứng dụng
NestJS ưu tiên @HttpCode(...). Next.js dùng mã trạng thái tĩnh từ Response/NextResponse; nếu không khai báo thì mặc định 200.
| HTTP Method | Mặc định của NestJS | Mặc định của Next.js |
|---|---|---|
| POST | 201 | 200 |
| GET | 200 | 200 |
| PUT / PATCH | 200 | 200 |
| DELETE | 200 | 200 |
Next.js App Router — phạm vi nhận diện
đã có bộ điều hợp và kiểm thử hồi quy; cần xác nhận khi chạy thực tế trên máyapp/api/users/[id]/route.ts → /api/users/{id}; route group (internal) không tạo segment.GET, POST, PUT, PATCH, DELETE.searchParams.get(), getAll() và headers.get() khi khóa là chuỗi tĩnh.request.json() dùng type annotation hoặc as Type; không xác định được kiểu dữ liệu → Unknown + cảnh báo.Response.json, NextResponse.json, new Response, new NextResponse và mã trạng thái tĩnh theo từng nhánh.HEAD/OPTIONS và catch-all [...slug]/[[...slug]] hiện chuyển sang Chưa đầy đủ (Incomplete).Câu hỏi thường gặp và xử lý sự cố
Các lưu ý quan trọng để tạo và xuất tệp chính xác.
Tại sao Swagger không cần tạo chỉ mục ngữ nghĩa?
Swagger quét trực tiếp cây thư mục bằng bộ phân tích AST tĩnh viết bằng Rust. Nó chạy độc lập, cực nhanh và không cần dùng tài nguyên cho quá trình tạo vector nhúng.
Khi nào nút "Sao chép câu lệnh" bị vô hiệu hóa?
Khi trạng thái phân tích là Chưa đầy đủ (Incomplete) (ví dụ mã nguồn bị lỗi cú pháp nghiêm trọng hoặc thiếu thông tin quan trọng). Đây là cơ chế bảo vệ an toàn chủ động nhằm ngăn chặn việc tạo tài liệu từ dữ liệu thiếu sót.
Phiên bản định tuyến nào của Next.js đang được hỗ trợ?
Hiện hỗ trợ Next.js App Router với app/**/route.ts. Pages Router pages/api/* chưa thuộc phạm vi hỗ trợ; HEAD/OPTIONS và catch-all route chưa được ánh xạ đầy đủ.
Nếu Bộ kiểm tra trên máy báo lỗi JSON từ ChatGPT thì sao?
Trình kiểm tra trên máy sẽ chỉ rõ vị trí theo con trỏ JSON (JSON Pointer) (ví dụ: $.paths['/users/{id}'].get.parameters[0].required). Bạn có thể gửi phần lỗi đó cho ChatGPT để yêu cầu chỉnh sửa, hoặc sửa trực tiếp trong khung nhập liệu.