OpenAPI Generator là một công cụ mã nguồn mở biến OpenAPI hoặc Swagger spec thành mã nguồn hoạt động: SDK client, server stub và tệp cấu hình. Bạn cài đặt CLI của nó, trỏ nó vào spec của mình, chọn một generator như typescript-axios hoặc spring, và nó sẽ viết mã vào một thư mục đầu ra. Hướng dẫn này chỉ cho bạn cách cài đặt nó, liệt kê các generator có sẵn và tạo client và server cho một số ngôn ngữ.
OpenAPI Generator là gì
OpenAPI Generator đọc mô tả API có thể đọc bằng máy và xuất mã nguồn từ đó. Cung cấp cho nó một tệp openapi.yaml (hoặc JSON) và nó có thể tạo một thư viện client để gọi API đó, một server stub để triển khai nó, cộng với tài liệu và cấu hình.
Nó hỗ trợ cả OpenAPI v2 (định dạng Swagger cũ hơn) và OpenAPI v3. Dự án được duy trì bởi tổ chức OpenAPITools trên GitHub, với các template cho hàng chục ngôn ngữ và framework.
Điểm khác biệt chính: đây là một trình tạo mã, không phải là trình tạo tài liệu. Các công cụ tài liệu như Swagger UI hoặc Redoc hiển thị spec của bạn thành các trang HTML dễ đọc. OpenAPI Generator thay vào đó tạo ra mã bạn biên dịch và triển khai. Nó cũng có thể xuất tài liệu Markdown, nhưng công việc chính của nó là SDK và stub.
Mối quan hệ với Swagger Codegen
Nếu bạn đã sử dụng Swagger Codegen, OpenAPI Generator sẽ cảm thấy quen thuộc. Nó được phân nhánh từ Swagger Codegen vào tháng 5 năm 2018, giữa các phiên bản Swagger Codegen 2.3.1 và 2.4.0, bởi hơn 40 trong số những người đóng góp và tạo template hàng đầu của nó.
Việc phân nhánh xảy ra sau bất đồng về hướng đi của Swagger Codegen 3.0.0. Cộng đồng muốn một chu kỳ phát hành nhanh hơn, cởi mở hơn. Các ghi chú phân nhánh chính thức mô tả dự án dựa trên Swagger Codegen 2.4.0-SNAPSHOT, vì vậy cả hai có nguồn gốc sâu xa. Nếu bạn đang cân nhắc giữa hai công cụ này, bài phân tích các lựa chọn thay thế Swagger Codegen sẽ đề cập đến những khác biệt thực tế.
Cài đặt OpenAPI Generator
Bạn có bốn cách cài đặt phổ biến. Chọn cách phù hợp nhất với ngăn xếp công nghệ của bạn.
npm (phổ biến nhất)
Trình bao bọc npm là điểm khởi đầu dễ dàng nhất cho hầu hết các nhóm. Nó tải xuống và quản lý JAR cơ bản cho bạn.
npm install @openapitools/openapi-generator-cli -g
Bạn cũng có thể chạy nó mà không cần cài đặt toàn cục:
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
JAR độc lập
OpenAPI Generator là một ứng dụng Java, vì vậy bạn có thể tải xuống JAR trực tiếp từ Maven Central và chạy nó bằng Java. Điều này hoàn toàn bỏ qua lớp npm hoặc Homebrew.
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
Kiểm tra Maven Central để biết số phiên bản mới nhất trước khi tải xuống.
Docker
Hình ảnh chính thức cho phép bạn tạo mã mà không cần cài đặt bất cứ thứ gì cục bộ. Gắn thư mục làm việc của bạn vào container để nó có thể đọc spec của bạn và ghi kết quả trở lại.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
Liệt kê các generator có sẵn
Trước khi bạn tạo bất cứ thứ gì, hãy xem có những generator nào. Mỗi generator nhắm mục tiêu một ngôn ngữ cộng với framework, như java, python, hoặc spring.
openapi-generator-cli list
Để có chế độ xem gọn gàng, mỗi dòng một mục, hãy sử dụng cờ rút gọn và phân tách bằng dấu phẩy:
openapi-generator-cli list -s | tr ',' '\n'
Danh sách phân tách các generator client (để gọi API) khỏi các generator server (để triển khai API), cộng với các generator tài liệu và schema.
Tạo một client SDK
Lệnh cốt lõi là generate. Nó có ba đối số bạn sẽ sử dụng mọi lúc:
-i, --input-spectrỏ đến tệp hoặc URL spec của bạn.-g, --generator-namechọn generator để chạy.-o, --outputđặt thư mục đầu ra.
Đây là một client TypeScript được xây dựng trên Axios:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Điều đó ghi một client đã được gõ vào ./client. Mỗi thao tác trong spec của bạn trở thành một phương thức, và mỗi schema trở thành một mô hình.
Mẫu tương tự hoạt động trên các ngôn ngữ. Thay đổi tên generator và thư mục đầu ra:
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
Vì mã được tạo từ một spec, mọi client đều nhất quán với hợp đồng. Khi spec thay đổi, bạn tạo lại và các SDK của bạn sẽ tuân theo.
Tạo server stub
Các generator server đảo ngược hướng. Thay vì mã gọi API của bạn, bạn sẽ nhận được một khung sườn triển khai nó, với định tuyến, mô hình yêu cầu và giao diện handler được kết nối. Bạn điền vào logic nghiệp vụ.
Đây là một Spring Boot server stub:
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
Dự án được tạo cung cấp cho bạn các controller và DTO khớp với spec của bạn. Bạn triển khai các phương thức giao diện, và các hình dạng yêu cầu và phản hồi đã được định nghĩa sẵn cho bạn. Điều này giữ cho server đang chạy phù hợp với hợp đồng đã xuất bản.
Cấu hình đầu ra
Đầu ra mặc định hiếm khi chính xác là những gì bạn muốn. OpenAPI Generator cung cấp cho bạn một số điều khiển.
Thuộc tính bổ sung
Hầu hết các generator hiển thị các tùy chọn theo ngôn ngữ thông qua --additional-properties (bí danh ngắn -p). Truyền chúng dưới dạng các cặp key=value được phân tách bằng dấu phẩy:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Mỗi generator tài liệu hóa các thuộc tính của riêng nó, vì vậy hãy kiểm tra trang generator để biết danh sách đầy đủ các khóa mà nó chấp nhận.
Một tệp cấu hình
Khi dòng lệnh trở nên dài, hãy di chuyển các tùy chọn vào một tệp cấu hình. Cả JSON và YAML đều được hỗ trợ.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
Một tệp cấu hình giữ cài đặt tạo mã của bạn trong kiểm soát phiên bản bên cạnh spec, giúp các bản dựng có thể tái tạo.
Bỏ qua tệp
OpenAPI Generator đọc một tệp .openapi-generator-ignore trong thư mục đầu ra. Nó sử dụng cùng cú pháp với .gitignore. Sử dụng nó để ngăn generator ghi đè lên các tệp bạn đã chỉnh sửa thủ công.
# .openapi-generator-ignore
*.md
src/custom/**
Bạn có thể trỏ đến một tệp bỏ qua ở một vị trí khác bằng --ignore-file-override <location>.
Template tùy chỉnh
Mỗi generator được điều khiển bởi các template Mustache. Nếu đầu ra mặc định không khớp với phong cách của bạn, hãy sao chép các template, chỉnh sửa chúng và truyền thư mục của bạn với -t:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
Đây là công cụ phù hợp khi bạn cần một tiêu đề tùy chỉnh, một client HTTP khác hoặc các quy ước đặt tên nội bộ được tích hợp vào mọi tệp được tạo.
Chạy trong CI
Việc tạo mã thuộc về pipeline của bạn, không phải trên máy tính xách tay của một nhà phát triển. Tạo lại client khi có bất kỳ thay đổi nào trong spec để SDK đã commit không bao giờ lệch khỏi hợp đồng. Đây là một bước GitHub Actions sử dụng npx:
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Bạn có thể làm hỏng bản dựng nếu đầu ra được tạo lại khác với những gì đã cam kết, điều này phát hiện các spec và SDK đã bị mất đồng bộ.
Giữ spec làm nguồn chân lý duy nhất của bạn
OpenAPI Generator chỉ tốt khi spec bạn cung cấp cho nó tốt. Đầu vào rác, đầu ra rác: một spec mơ hồ hoặc không hợp lệ sẽ tạo ra một SDK mơ hồ hoặc bị hỏng. Vì vậy, bước giá trị nhất xảy ra trước khi bạn chạy generate. Bạn làm cho spec chính xác, đầy đủ và ổn định.
Đây là lúc Apidog phù hợp. Apidog là một nền tảng API tất cả trong một tích hợp OpenAPI, vì vậy công việc thiết kế và spec của bạn là cùng một tạo phẩm. Bạn thiết kế hoặc nhập API, và Apidog giữ tài liệu OpenAPI làm nguồn chân lý mà mọi thứ khác đều bắt nguồn từ đó.
Một quy trình làm việc sạch sẽ trông như thế này:
- Thiết kế hoặc nhập spec OpenAPI trong Apidog. Hỗ trợ phân nhánh cho phép bạn làm việc với các thay đổi một cách độc lập, tương tự như kiểm soát phiên bản OpenAPI bằng Git.
- Xác thực và lint spec trước khi bạn tạo. Một spec vượt qua OpenAPI linter và Swagger validator sẽ tạo ra mã sạch hơn với ít bất ngờ hơn.
- Xuất spec đã được xác thực, sau đó cung cấp nó cho OpenAPI Generator cho các SDK và stub của bạn.
Bạn cũng có thể giữ spec đồng bộ hóa với kho lưu trữ của mình, ví dụ bằng cách đồng bộ hóa spec OpenAPI với GitHub, và xem xét các thay đổi với OpenAPI diff trước khi chúng được triển khai. Nếu bạn đang chuyển từ các công cụ cũ hơn, so sánh các lựa chọn thay thế Swagger cho thiết kế và kiểm thử API là một điểm khởi đầu tốt.
Apidog dừng ở đâu và OpenAPI Generator bắt đầu từ đâu
Cần phải chính xác ở đây. Apidog không tạo ra các SDK client hoặc server stub đầy đủ. Đó là công việc của OpenAPI Generator, và hai công cụ này bổ sung cho nhau chứ không cạnh tranh.
Apidog cung cấp cho bạn các đoạn mã yêu cầu client sẵn sàng sao chép cho mỗi endpoint, bằng nhiều ngôn ngữ và client HTTP. Đó là các ví dụ cho mỗi yêu cầu bạn có thể dán vào một script, chứ không phải là một SDK được đóng gói. Để có một thư viện được tạo, có phiên bản hoặc một khung sườn server, bạn chạy OpenAPI Generator trên spec mà Apidog tạo ra.
Apidog cũng phát hành trình chạy kiểm thử dòng lệnh của riêng mình, Apidog CLI, tách biệt với việc tạo mã. Nó chạy các kiểm thử API của bạn trong CI; nó không tạo SDK. Cài đặt và sử dụng nó như sau:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
Bạn truyền xác thực bằng --access-token, -t chọn kịch bản kiểm thử, -e chọn môi trường để chạy, và -r chọn các trình báo cáo. Chạy nó trên bản phát hành Node.js LTS hiện tại. Để biết chi tiết thiết lập, xem hướng dẫn cài đặt Apidog CLI và hướng dẫn chi tiết về kiểm thử REST API từ dòng lệnh.
Vì vậy, quy trình hoàn chỉnh là: thiết kế và xác thực spec trong Apidog, tạo SDK và stub bằng OpenAPI Generator, sau đó xác minh API đang chạy bằng Apidog CLI.
Hãy dùng thử Apidog miễn phí, không cần thẻ tín dụng.
Các câu hỏi thường gặp
OpenAPI Generator là gì?
OpenAPI Generator là một công cụ mã nguồn mở từ tổ chức OpenAPITools tạo mã từ một spec OpenAPI hoặc Swagger. Nó tạo ra các SDK client, server stub, tài liệu và tệp cấu hình, đồng thời hỗ trợ cả OpenAPI v2 và v3.
Sử dụng OpenAPI Generator như thế nào?
Cài đặt CLI (ví dụ: npm install @openapitools/openapi-generator-cli -g), sau đó chạy generate với ba cờ: -i cho spec của bạn, -g cho generator, và -o cho thư mục đầu ra. Chạy openapi-generator-cli list trước để xem tất cả các generator có sẵn.
OpenAPI Generator hoạt động như thế nào?
Nó phân tích cú pháp spec của bạn thành một mô hình nội bộ, sau đó hiển thị mô hình đó thông qua các template Mustache cho mục tiêu bạn đã chọn. Mỗi thao tác trở thành một phương thức hoặc handler, và mỗi schema trở thành một mô hình có kiểu. Bạn có thể ghi đè các template bằng -t để thay đổi đầu ra.
Làm cách nào để tạo một client SDK từ một spec OpenAPI?
Chọn một generator client và chạy generate. Ví dụ: openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client xây dựng một client TypeScript đã được gõ. Thay thế typescript-axios bằng java, python, hoặc go để nhắm mục tiêu các ngôn ngữ khác.
Làm cách nào để tạo server stub?
Chọn một generator server. Đối với một khung sườn Spring Boot, chạy openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring. Đầu ra bao gồm các controller và mô hình yêu cầu từ spec của bạn, và bạn triển khai logic handler.
Sự khác biệt giữa OpenAPI Generator và Swagger Codegen là gì?
OpenAPI Generator được phân nhánh từ Swagger Codegen vào tháng 5 năm 2018 bởi hơn 40 người đóng góp của nó, những người muốn một chu kỳ phát hành nhanh hơn, do cộng đồng điều khiển. Cả hai có một nền tảng chung, nhưng OpenAPI Generator hiện có lộ trình, bộ generator và lịch phát hành riêng.
Làm cách nào để tạo một PHP SDK từ một spec OpenAPI?
Sử dụng generator php: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php. Chạy openapi-generator-cli list để xác nhận tên generator chính xác và để xem các tùy chọn framework PHP khác trước khi bạn tạo.