DEV Community

Cover image for OpenAPI Generator: Hướng dẫn tạo mã client và server API
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

OpenAPI Generator: Hướng dẫn tạo mã client và server API

OpenAPI Generator là công cụ mã nguồn mở dùng để biến OpenAPI hoặc Swagger spec thành mã nguồn có thể dùng ngay: SDK client, server stub, tài liệu và tệp cấu hình. Quy trình cơ bản là: cài CLI, trỏ vào openapi.yaml, chọn generator như typescript-axios hoặc spring, rồi xuất mã vào thư mục đích.

Dùng thử Apidog ngay hôm nay

OpenAPI Generator là gì

OpenAPI Generator đọc mô tả API ở định dạng máy có thể hiểu được và sinh mã từ đó. Bạn cung cấp một tệp openapi.yaml hoặc JSON, công cụ có thể tạo:

  • SDK client để gọi API
  • Server stub để triển khai API
  • Model/schema tương ứng với spec
  • Tài liệu và cấu hình dự án

Công cụ này hỗ trợ cả OpenAPI v2, tức Swagger cũ, và OpenAPI v3. Dự án được duy trì bởi tổ chức OpenAPITools trên GitHub, với template cho nhiều ngôn ngữ và framework.

Điểm cần phân biệt: OpenAPI Generator là trình tạo mã, không phải công cụ hiển thị tài liệu API. Swagger UI hoặc Redoc render spec thành HTML dễ đọc. OpenAPI Generator tạo mã để bạn build, test và triển khai. Nó cũng có thể sinh Markdown, nhưng use case chính vẫn là SDK và server stub.

Mối quan hệ với Swagger Codegen

Nếu bạn từng dùng Swagger Codegen, OpenAPI Generator sẽ khá quen thuộc. Công cụ này đượ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 contributor và template creator hàng đầu.

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 chu kỳ phát hành nhanh hơn và cởi mở hơn. Nếu bạn đang so sánh hai công cụ, bài viết về các lựa chọn thay thế Swagger Codegen phân tích các khác biệt thực tế.

Cài đặt OpenAPI Generator

Bạn có thể cài OpenAPI Generator theo nhiều cách. Chọn cách phù hợp với môi trường build của dự án.

Cài bằng npm

Đây là cách phổ biến nhất với các nhóm JavaScript/TypeScript. Gói npm sẽ tải và quản lý JAR phía sau cho bạn.

npm install @openapitools/openapi-generator-cli -g
Enter fullscreen mode Exit fullscreen mode

Kiểm tra phiên bản:

openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Hoặc chạy không cần cài global:

npx @openapitools/openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Cài bằng Homebrew trên macOS 

brew install openapi-generator
Enter fullscreen mode Exit fullscreen mode

Chạy bằng JAR độc lập

OpenAPI Generator là ứng dụng Java, vì vậy bạn có thể tải JAR trực tiếp từ Maven Central và chạy bằng Java.

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
Enter fullscreen mode Exit fullscreen mode

Trước khi tải, hãy kiểm tra Maven Central để lấy phiên bản mới nhất.

Chạy bằng Docker

Docker phù hợp khi bạn không muốn cài thêm tool trên máy local hoặc muốn chạy ổn định trong CI.

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
Enter fullscreen mode Exit fullscreen mode

Ở đây:

  • -v "${PWD}:/local" mount thư mục hiện tại vào container
  • -i /local/openapi.yaml là file spec
  • -g go chọn generator Go
  • -o /local/out/go là thư mục đầu ra

Liệt kê các generator có sẵn

Trước khi sinh mã, hãy kiểm tra generator nào phù hợp với stack của bạn.

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

Để xem danh sách gọn hơn, mỗi dòng một generator:

openapi-generator-cli list -s | tr ',' '\n'
Enter fullscreen mode Exit fullscreen mode

Danh sách này thường được chia thành:

  • Client generator: tạo SDK để gọi API
  • Server generator: tạo server stub để triển khai API
  • Documentation generator: tạo tài liệu
  • Schema/config generator: tạo schema hoặc cấu hình phụ trợ

Ví dụ các generator thường dùng:

typescript-axios
typescript-fetch
java
python
go
php
spring
nodejs-express-server
Enter fullscreen mode Exit fullscreen mode

Tạo client SDK

Lệnh chính bạn sẽ dùng là generate.

Cú pháp tối thiểu:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g <generator-name> \
  -o <output-dir>
Enter fullscreen mode Exit fullscreen mode

Trong đó:

  • -i, --input-spec: đường dẫn hoặc URL tới OpenAPI spec
  • -g, --generator-name: generator cần chạy
  • -o, --output: thư mục xuất mã

Ví dụ: tạo TypeScript SDK dùng Axios 

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Sau khi chạy, thư mục ./client sẽ chứa client TypeScript đã được typed. Các operation trong spec trở thành method, còn schema trở thành model.

Ví dụ nếu spec có endpoint GET /users/{id}, SDK được sinh thường sẽ có method tương ứng để gọi endpoint đó, thay vì bạn phải tự viết request HTTP thủ công.

Tạo SDK cho nhiều ngôn ngữ

Bạn chỉ cần đổi 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
openapi-generator-cli generate -i openapi.yaml -g php    -o ./client-php
Enter fullscreen mode Exit fullscreen mode

Cách làm này giúp nhiều SDK cùng bám theo một contract API duy nhất. Khi spec thay đổi, bạn generate lại để đồng bộ client.

Tạo server stub

Server generator làm chiều ngược lại với client generator. Thay vì tạo mã gọi API, nó tạo khung server để bạn triển khai API.

Server stub thường bao gồm:

  • Route/controller
  • Request/response model
  • Interface hoặc handler rỗng
  • Cấu trúc project theo framework đã chọn

Ví dụ: tạo Spring Boot server stub 

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

Đầu ra sẽ có controller và DTO khớp với spec. Bạn chỉ cần triển khai business logic trong các handler hoặc interface được sinh ra.

Cách này giúp server implementation luôn bám theo contract đã công bố.

Cấu hình đầu ra

Đầu ra mặc định thường chưa khớp hoàn toàn với convention của dự án. OpenAPI Generator hỗ trợ nhiều cách tùy chỉnh.

Dùng --additional-properties

Hầu hết generator có option riêng thông qua --additional-properties, hoặc viết ngắn là -p.

Ví dụ với typescript-axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Enter fullscreen mode Exit fullscreen mode

Các option trong ví dụ:

  • npmName=@acme/api-client: đặt tên package npm
  • supportsES6=true: bật hỗ trợ ES6
  • withSeparateModelsAndApi=true: tách model và API thành các phần riêng

Mỗi generator có bộ option riêng. Bạn nên kiểm tra tài liệu của generator trước khi cố định cấu hình.

Dùng file cấu hình

Khi command quá dài, hãy chuyển option vào file cấu hình. OpenAPI Generator hỗ trợ JSON và YAML.

Ví dụ chạy với file config.yaml:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -c config.yaml
Enter fullscreen mode Exit fullscreen mode

Ví dụ config.yaml:

npmName: "@acme/api-client"
supportsES6: true
withSeparateModelsAndApi: true
Enter fullscreen mode Exit fullscreen mode

Đưa file cấu hình vào version control giúp quá trình generate có thể lặp lại trên local và CI.

Bỏ qua file không muốn ghi đè

OpenAPI Generator đọc file .openapi-generator-ignore trong thư mục đầu ra. Cú pháp tương tự .gitignore.

Ví dụ:

# .openapi-generator-ignore
*.md
src/custom/**
Enter fullscreen mode Exit fullscreen mode

Dùng file này khi bạn có một số file custom không muốn generator ghi đè.

Bạn cũng có thể chỉ định file ignore ở vị trí khác:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --ignore-file-override ./generator-ignore
Enter fullscreen mode Exit fullscreen mode

Dùng template tùy chỉnh

Mỗi generator được điều khiển bởi template Mustache. Nếu output mặc định không phù hợp với convention nội bộ, bạn có thể override template.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./my-templates
Enter fullscreen mode Exit fullscreen mode

Template tùy chỉnh hữu ích khi bạn cần:

  • Thêm header/license vào mọi file
  • Dùng HTTP client khác
  • Đổi naming convention
  • Điều chỉnh cấu trúc thư mục
  • Áp dụng coding style nội bộ

Chạy OpenAPI Generator trong CI

Việc generate mã nên nằm trong pipeline, không phụ thuộc vào máy của từng developer. Điều này giúp phát hiện SDK bị lệch khỏi OpenAPI spec.

Ví dụ GitHub Actions dùng npx:

- name: Generate API client
  run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Enter fullscreen mode Exit fullscreen mode

Bạn cũng có thể fail build nếu output generate lại khác với mã đã commit:

- name: Generate API client
  run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

- name: Check generated diff
  run: git diff --exit-code ./client
Enter fullscreen mode Exit fullscreen mode

Cách này buộc mọi thay đổi trong openapi.yaml phải đi kèm SDK được cập nhật.

Giữ OpenAPI spec làm nguồn chân lý duy nhất

OpenAPI Generator chỉ tốt khi spec đầu vào tốt. Nếu spec thiếu, mơ hồ hoặc không hợp lệ, SDK và server stub được sinh ra cũng sẽ khó dùng hoặc bị lỗi.

Trước khi chạy generate, hãy đảm bảo spec:

  • Có đầy đủ path, method và response
  • Khai báo schema rõ ràng
  • Có status code phù hợp
  • Không thiếu required field
  • Được validate/lint trước khi đưa vào CI
  • Được version control cùng source code

Đây là lúc Apidog phù hợp. Apidog là nền tảng API tất cả trong một có tích hợp OpenAPI, giúp bạn thiết kế hoặc import API và giữ OpenAPI spec làm nguồn chân lý.

Một workflow thực tế:

  1. Thiết kế hoặc import OpenAPI spec trong Apidog. Hỗ trợ phân nhánh giúp bạn làm việc với thay đổi độc lập, tương tự kiểm soát phiên bản OpenAPI bằng Git.
  2. Validate và lint spec trước khi generate. Một spec vượt qua OpenAPI linter và Swagger validator sẽ tạo mã ổn định hơn.
  3. Export spec đã được xác thực.
  4. Chạy OpenAPI Generator để tạo SDK client hoặc server stub.
  5. Commit output hoặc publish SDK theo quy trình release của bạn.

Bạn cũng có thể đồng bộ spec với repository, ví dụ bằng cách đồng bộ hóa OpenAPI spec với GitHub, rồi review thay đổi bằng OpenAPI diff trước khi triển khai. Nếu bạn đang chuyển từ tool cũ, bài viết về các lựa chọn thay thế Swagger cho thiết kế và kiểm thử API là điểm bắt đầu tốt.

Apidog dừng ở đâu và OpenAPI Generator bắt đầu từ đâu

Cần phân biệt rõ vai trò của từng công cụ.

Apidog không tạo SDK client hoặc server stub đầy đủ. Việc đó thuộc về OpenAPI Generator. Hai công cụ bổ sung cho nhau:

  • Apidog: thiết kế, quản lý, validate, lint và kiểm thử API dựa trên OpenAPI
  • OpenAPI Generator: sinh SDK client, server stub, model và cấu hình từ spec

Apidog có thể cung cấp các đoạn mã request client cho từng endpoint bằng nhiều ngôn ngữ và HTTP client. Đây là snippet để copy vào script hoặc ví dụ sử dụng, không phải SDK được đóng gói và version hóa.

Để tạo SDK hoàn chỉnh, hãy export OpenAPI spec từ Apidog rồi chạy OpenAPI Generator.

Apidog cũng có CLI riêng để chạy kiểm thử API trong CI: Apidog CLI. Công cụ này dùng để chạy test, không dùng để generate SDK.

Cài đặt:

npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

Chạy test:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <testScenarioId> \
  -e <envId> \
  -r cli,html \
  -n 1
Enter fullscreen mode Exit fullscreen mode

Trong đó:

  • --access-token: token xác thực
  • -t: test scenario cần chạy
  • -e: environment
  • -r: reporter, ví dụ cli và html
  • -n: số lần chạy

Bạn nên chạy trên bản Node.js LTS hiện tại. Xem thêm hướng dẫn cài đặt Apidog CLI và hướng dẫn kiểm thử REST API từ dòng lệnh.

Workflow hoàn chỉnh có thể là:

Thiết kế API trong Apidog
        ↓
Validate/lint OpenAPI spec
        ↓
Export openapi.yaml
        ↓
Generate SDK/server stub bằng OpenAPI Generator
        ↓
Chạy API test bằng Apidog CLI trong CI
Enter fullscreen mode Exit fullscreen mode

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à công cụ mã nguồn mở từ tổ chức OpenAPITools dùng để tạo mã từ OpenAPI hoặc Swagger spec. Nó có thể tạo SDK client, server stub, tài liệu và tệp cấu hình, đồng thời hỗ trợ OpenAPI v2 và v3.

Sử dụng OpenAPI Generator như thế nào?

Cài CLI, ví dụ:

npm install @openapitools/openapi-generator-cli -g
Enter fullscreen mode Exit fullscreen mode

Sau đó chạy:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Chạy lệnh sau để xem generator có sẵn:

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

OpenAPI Generator hoạt động như thế nào?

Nó phân tích OpenAPI spec thành model nội bộ, sau đó render model đó qua các template Mustache của generator đã chọn. Operation trở thành method hoặc handler. Schema trở thành model có kiểu. Bạn có thể override template bằng -t.

Làm cách nào để tạo client SDK từ OpenAPI spec?

Chọn client generator rồi chạy generate.

Ví dụ tạo TypeScript SDK dùng Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Đổi typescript-axios thành java, python, go hoặc php nếu cần ngôn ngữ khác.

Làm cách nào để tạo server stub?

Chọn server generator. Ví dụ với Spring Boot:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

Output sẽ bao gồm controller, model request/response và các điểm để bạn triển khai business logic.

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 contributor. Cả hai có nền tảng chung, nhưng OpenAPI Generator có lộ trình, bộ generator và chu kỳ phát hành riêng do cộng đồng duy trì.

Làm cách nào để tạo PHP SDK từ OpenAPI spec?

Dùng generator php:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g php \
  -o ./client-php
Enter fullscreen mode Exit fullscreen mode

Bạn nên chạy openapi-generator-cli list trước để kiểm tra tên generator và các biến thể framework PHP khác.

Top comments (0)