DEV Community

Cover image for OpenAPI Generator: สร้างโค้ด API Client และ Server อย่างไร
Thanawat Wongchai
Thanawat Wongchai

Posted on • Originally published at apidog.com

OpenAPI Generator: สร้างโค้ด API Client และ Server อย่างไร

OpenAPI Generator เป็นเครื่องมือโอเพนซอร์สสำหรับแปลง OpenAPI/Swagger spec ให้เป็นโค้ดที่ใช้งานได้จริง เช่น client SDK, server stub, เอกสาร และไฟล์ config วิธีใช้งานหลักคือ ติดตั้ง CLI, ระบุไฟล์ spec, เลือก generator เช่น typescript-axios หรือ spring, แล้วกำหนดโฟลเดอร์เอาต์พุต บทความนี้สรุปขั้นตอนติดตั้ง ดูรายชื่อ generator และสร้าง client/server สำหรับหลายภาษาแบบลงมือทำได้ทันที

ลองใช้ Apidog วันนี้

OpenAPI Generator คืออะไร

OpenAPI Generator อ่านไฟล์คำอธิบาย API ที่เครื่องอ่านได้ เช่น openapi.yaml หรือ JSON แล้วสร้างซอร์สโค้ดจาก spec นั้นได้ เช่น:

  • client SDK สำหรับเรียก API
  • server stub สำหรับเริ่ม implement API
  • model/DTO ตาม schema
  • เอกสารและไฟล์ configuration

เครื่องมือนี้รองรับทั้ง OpenAPI v2 หรือ Swagger เดิม และ OpenAPI v3 โดยโปรเจกต์อยู่ภายใต้องค์กร OpenAPITools บน GitHub และมีเทมเพลตสำหรับหลายภาษาและเฟรมเวิร์ก

จุดสำคัญคือ OpenAPI Generator เป็น code generator ไม่ใช่แค่ documentation generator เครื่องมืออย่าง Swagger UI หรือ Redoc แสดง spec เป็นหน้า HTML ให้มนุษย์อ่าน แต่ OpenAPI Generator สร้างโค้ดที่คุณนำไป build, test และใช้งานจริงได้

เกี่ยวข้องกับ Swagger Codegen อย่างไร

ถ้าคุณเคยใช้ Swagger Codegen มาก่อน คำสั่งและแนวคิดของ OpenAPI Generator จะคุ้นเคยมาก เพราะ OpenAPI Generator ถูก fork ออกจาก Swagger Codegen ในเดือนพฤษภาคม 2018 ระหว่าง Swagger Codegen 2.3.1 และ 2.4.0 โดยผู้มีส่วนร่วมและผู้ดูแลเทมเพลตมากกว่า 40 คน

การ fork เกิดจากความเห็นต่างเรื่องทิศทางของ Swagger Codegen 3.0.0 โดยชุมชนต้องการรอบ release ที่เร็วและเปิดกว้างกว่า หากคุณกำลังเปรียบเทียบสองเครื่องมือนี้ อ่านเพิ่มเติมได้ที่ ทางเลือก Swagger Codegen

การติดตั้ง OpenAPI Generator

เลือกวิธีติดตั้งตาม stack ที่ทีมคุณใช้งาน

npm

วิธีนี้เหมาะกับทีม JavaScript/TypeScript เพราะ npm wrapper จะช่วยดาวน์โหลดและจัดการ JAR ให้

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

ตรวจสอบเวอร์ชัน:

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

หรือรันโดยไม่ติดตั้ง global:

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

Homebrew บน macOS 

brew install openapi-generator
Enter fullscreen mode Exit fullscreen mode

Standalone JAR

OpenAPI Generator เป็น Java application คุณจึงดาวน์โหลด JAR จาก Maven Central แล้วรันด้วย 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

ก่อนดาวน์โหลด ควรตรวจสอบ Maven Central เพื่อดูเวอร์ชันล่าสุด

Docker

ถ้าไม่ต้องการติดตั้ง dependency ในเครื่อง ใช้ Docker image อย่างเป็นทางการได้ โดย mount working directory เข้า container เพื่อให้ generator อ่าน spec และเขียน output กลับออกมา

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

ดูรายชื่อ generator ที่มีอยู่

ก่อนสร้างโค้ด ให้ดูว่า OpenAPI Generator รองรับ target ใดบ้าง

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

ถ้าต้องการ output แบบหนึ่งบรรทัดต่อ generator:

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

รายชื่อจะแยกเป็นกลุ่ม เช่น:

  • client generator สำหรับสร้าง SDK
  • server generator สำหรับสร้าง server stub
  • documentation generator
  • schema/config generator

ตัวอย่าง generator ที่พบบ่อย:

  • typescript-axios
  • java
  • python
  • go
  • php
  • spring

สร้าง client SDK

คำสั่งหลักคือ generate โดยใช้ option หลัก 3 ตัว:

  • -i หรือ --input-spec: path หรือ URL ของ OpenAPI spec
  • -g หรือ --generator-name: ชื่อ generator
  • -o หรือ --output: โฟลเดอร์ output

ตัวอย่างสร้าง TypeScript client ที่ใช้ Axios:

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

ผลลัพธ์ใน ./client จะมี client code, method สำหรับ operation ต่าง ๆ และ model ตาม schema ใน spec

สร้าง client สำหรับภาษาอื่นได้ด้วย pattern เดียวกัน:

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

เมื่อ spec เปลี่ยน ให้ generate ใหม่เพื่อให้ SDK สอดคล้องกับ API contract ล่าสุด

สร้าง server stubs

server generator จะสร้างโครงสร้างฝั่ง server จาก spec เช่น routes, controllers, request/response models และ interface สำหรับ handler จากนั้นคุณเติม business logic เอง

ตัวอย่างสร้าง Spring Boot server stub:

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

โปรเจกต์ที่สร้างขึ้นจะมี controllers และ DTOs ที่ตรงกับ OpenAPI spec ช่วยให้ implementation สอดคล้องกับ contract ที่เผยแพร่

กำหนดค่า output

ค่า default ของ generator อาจยังไม่ตรงกับ convention ของโปรเจกต์ คุณสามารถปรับ output ได้หลายวิธี

ใช้ additional properties

generator ส่วนใหญ่รองรับ option เฉพาะภาษาผ่าน --additional-properties หรือ -p

ตัวอย่าง 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

แต่ละ generator มี property ไม่เหมือนกัน ควรดูเอกสารของ generator นั้นก่อนใช้งานจริง

ใช้ config file

ถ้า command ยาวเกินไป ให้ย้าย option ไปไว้ในไฟล์ config ได้ รองรับทั้ง JSON และ YAML

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

การเก็บ config file ไว้ใน repo พร้อม spec ช่วยให้การ generate ทำซ้ำได้ในเครื่องนักพัฒนาและ CI

ละเว้นไฟล์ที่ไม่ต้องการให้เขียนทับ

OpenAPI Generator อ่านไฟล์ .openapi-generator-ignore ใน output directory โดยใช้ syntax คล้าย .gitignore

ตัวอย่าง:

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

ใช้เมื่อคุณมีไฟล์ที่แก้ด้วยมือและไม่ต้องการให้ generator เขียนทับ

ถ้าต้องการใช้ ignore file จากตำแหน่งอื่น:

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

ใช้ custom templates

generator ใช้ Mustache template ในการ render output ถ้าต้องการปรับรูปแบบไฟล์ให้ตรงกับมาตรฐานองค์กร ให้ copy template มาแก้ แล้วส่ง path ด้วย -t

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

เหมาะกับกรณีเช่น:

  • เพิ่ม file header เฉพาะองค์กร
  • เปลี่ยน HTTP client
  • บังคับ naming convention
  • ปรับโครงสร้างไฟล์ที่ generate

รันใน CI

การ generate code ควรอยู่ใน pipeline ไม่ควรผูกกับเครื่องของนักพัฒนาคนใดคนหนึ่ง ตัวอย่าง GitHub Actions:

- 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

คุณสามารถทำให้ build fail ได้ถ้า generated output แตกต่างจากไฟล์ที่ commit ไว้ เพื่อจับปัญหา spec และ SDK ไม่ตรงกัน

ตัวอย่างแนวทางตรวจ diff:

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

- name: Check generated files
  run: git diff --exit-code
Enter fullscreen mode Exit fullscreen mode

เก็บ spec เป็นแหล่งความจริงเดียว

OpenAPI Generator จะให้ผลลัพธ์ดีเท่ากับ spec ที่คุณป้อนเข้าไปเท่านั้น ถ้า spec คลุมเครือหรือไม่ถูกต้อง SDK และ server stub ที่ได้ก็จะมีปัญหาตามไปด้วย

ขั้นตอนที่ควรทำก่อนรัน generate คือ:

  1. ออกแบบ API ให้ชัดเจน
  2. ตรวจ schema, request และ response ให้ครบ
  3. lint/validate spec
  4. version หรือ review การเปลี่ยนแปลงของ spec
  5. generate code จาก spec ที่ผ่านการตรวจแล้ว

นี่คือจุดที่ Apidog ช่วยได้ Apidog เป็นแพลตฟอร์ม API แบบ all-in-one ที่ทำงานแบบ OpenAPI-native คุณสามารถออกแบบหรือนำเข้า API และใช้ OpenAPI spec เป็นแหล่งความจริงร่วมกันสำหรับเอกสาร การทดสอบ และ workflow อื่น ๆ

workflow ที่ใช้งานร่วมกับ OpenAPI Generator ได้คือ:

  1. ออกแบบหรือนำเข้า OpenAPI spec ใน Apidog

    การรองรับ Branch ช่วยให้ทำงานกับการเปลี่ยนแปลงได้คล้ายกับ การควบคุมเวอร์ชัน OpenAPI ด้วย Git

  2. ตรวจสอบและ lint spec ก่อน generate

    spec ที่ผ่าน OpenAPI linter และ Swagger validator จะช่วยลด error ใน generated code

  3. ส่งออก spec ที่ผ่านการตรวจสอบแล้ว

    จากนั้นนำไปใช้กับ OpenAPI Generator เพื่อสร้าง SDK และ stubs

คุณยังสามารถ sync spec กับ repo เช่น ซิงค์ OpenAPI spec ไปยัง GitHub และตรวจ breaking changes ด้วย OpenAPI diff ก่อนเผยแพร่ หากกำลังเปลี่ยนจากเครื่องมือเดิม อ่านเพิ่มได้ที่ ทางเลือก Swagger สำหรับการออกแบบและการทดสอบ API

Apidog สิ้นสุดตรงไหน และ OpenAPI Generator เริ่มตรงไหน

ควรแยกบทบาทให้ชัดเจน:

  • Apidog ใช้สำหรับออกแบบ จัดการ ตรวจสอบ เอกสาร และทดสอบ API จาก OpenAPI spec
  • OpenAPI Generator ใช้สำหรับสร้าง client SDK และ server stub แบบเต็มจาก spec

Apidog ไม่ได้สร้าง client SDK หรือ server stub แบบแพ็กเกจเต็มเหมือน OpenAPI Generator แต่ Apidog มี request code snippets สำหรับแต่ละ endpoint ในหลายภาษาและหลาย HTTP client ซึ่งเหมาะกับการ copy ไปใช้เป็นตัวอย่างต่อ request

ถ้าต้องการ SDK ที่เป็น library มี version และโครงสร้างโปรเจกต์ ให้ export spec จาก Apidog แล้วรัน OpenAPI Generator

Apidog ยังมี CLI สำหรับรัน API test ใน CI คือ Apidog CLI ซึ่งแยกจากการ generate code

ติดตั้ง:

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

รัน test scenario:

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

ความหมายของ option หลัก:

  • --access-token: token สำหรับ authentication
  • -t: test scenario ID
  • -e: environment ID
  • -r: reporter เช่น cli หรือ html
  • -n: จำนวนรอบที่รัน

รายละเอียดเพิ่มเติมดูได้ที่ คู่มือการติดตั้ง Apidog CLI และ การทดสอบ REST API จาก command line

สรุป workflow:

  1. ออกแบบและตรวจสอบ spec ใน Apidog
  2. สร้าง SDK และ server stubs ด้วย OpenAPI Generator
  3. รันทดสอบ API ที่ deploy แล้วด้วย Apidog CLI

ลองใช้ Apidog ฟรี ไม่ต้องใช้บัตรเครดิต

คำถามที่พบบ่อย

OpenAPI Generator คืออะไร?

OpenAPI Generator เป็นเครื่องมือโอเพนซอร์สจาก OpenAPITools ที่สร้างโค้ดจาก OpenAPI หรือ Swagger spec เช่น client SDK, server stub, เอกสาร และไฟล์ config รองรับทั้ง OpenAPI v2 และ v3

ใช้ OpenAPI Generator อย่างไร?

ติดตั้ง CLI แล้วรัน generate พร้อม option หลัก:

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

ใช้ openapi-generator-cli list เพื่อดู generator ที่มีอยู่ก่อนเลือก target

OpenAPI Generator ทำงานอย่างไร?

OpenAPI Generator parse spec เป็น internal model แล้ว render ผ่าน Mustache templates ของ generator ที่เลือก แต่ละ operation จะกลายเป็น method หรือ handler และแต่ละ schema จะกลายเป็น typed model คุณสามารถ override template ด้วย -t ได้

สร้าง client SDK จาก OpenAPI spec ได้อย่างไร?

เลือก client generator แล้วรัน generate เช่น:

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

เปลี่ยน typescript-axios เป็น java, python, go หรือ php เพื่อสร้าง SDK ภาษาอื่น

สร้าง server stubs ได้อย่างไร?

เลือก server generator เช่น spring:

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

output จะมี controllers, models และโครงสร้างพื้นฐานตาม spec จากนั้นคุณ implement business logic เพิ่มเอง

OpenAPI Generator ต่างจาก Swagger Codegen อย่างไร?

OpenAPI Generator ถูก fork ออกจาก Swagger Codegen ในเดือนพฤษภาคม 2018 โดยผู้มีส่วนร่วมมากกว่า 40 คน ทั้งสองมีรากฐานร่วมกัน แต่ OpenAPI Generator มี roadmap, generator set และ release cadence ของตัวเอง

สร้าง PHP SDK จาก OpenAPI spec ได้อย่างไร?

ใช้ php generator:

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

ก่อนใช้งานจริง ควรรัน openapi-generator-cli list เพื่อยืนยันชื่อ generator และดูตัวเลือก PHP อื่น ๆ ที่รองรับ

Top comments (0)