OpenAPI Generator เป็นเครื่องมือโอเพนซอร์สที่แปลง OpenAPI หรือ Swagger spec ให้เป็นโค้ดที่ใช้งานได้จริง: เช่น client SDKs, server stubs และไฟล์การกำหนดค่า คุณติดตั้ง CLI ของมัน ชี้ไปที่ spec ของคุณ เลือก generator เช่น typescript-axios หรือ spring และมันจะเขียนโค้ดลงในโฟลเดอร์เอาต์พุต คู่มือนี้จะแสดงวิธีการติดตั้ง การแสดงรายการ generator ที่มีอยู่ และการสร้าง client และ server สำหรับหลายภาษา
OpenAPI Generator คืออะไร
OpenAPI Generator อ่านคำอธิบาย API ที่เครื่องอ่านได้และสร้างซอร์สโค้ดจากมัน หากคุณให้ไฟล์ openapi.yaml (หรือ JSON) แก่มัน มันสามารถสร้างไลบรารีไคลเอ็นต์สำหรับการเรียก API นั้น, server stub ที่ใช้งาน API นั้น รวมถึงเอกสารและไฟล์การกำหนดค่าได้
มันรองรับทั้ง OpenAPI v2 (รูปแบบ Swagger รุ่นเก่า) และ OpenAPI v3 โปรเจกต์นี้ได้รับการดูแลโดยองค์กร OpenAPITools บน GitHub โดยมีเทมเพลตสำหรับภาษาและเฟรมเวิร์กมากมาย
ข้อแตกต่างที่สำคัญคือ: นี่คือตัวสร้างโค้ด ไม่ใช่ตัวสร้างเอกสาร เครื่องมือสร้างเอกสารอย่าง Swagger UI หรือ Redoc แสดง spec ของคุณในรูปแบบ HTML ที่มนุษย์อ่านได้ แต่ OpenAPI Generator สร้างโค้ดที่คุณคอมไพล์และใช้งาน มันสามารถสร้างเอกสาร Markdown ได้ด้วย แต่ภารกิจหลักของมันคือ SDKs และ stubs
มันเกี่ยวข้องกับ Swagger Codegen อย่างไร
หากคุณเคยใช้ Swagger Codegen คุณจะรู้สึกคุ้นเคยกับ OpenAPI Generator มันถูกแยกออกมาจาก Swagger Codegen ในเดือนพฤษภาคม 2018 ระหว่าง Swagger Codegen เวอร์ชัน 2.3.1 และ 2.4.0 โดยผู้มีส่วนร่วมและผู้สร้างเทมเพลตชั้นนำมากกว่า 40 คน
การแยกโปรเจกต์เกิดขึ้นหลังจากการไม่เห็นด้วยกับทิศทางของ Swagger Codegen 3.0.0 ชุมชนต้องการวงจรการเผยแพร่ที่รวดเร็วและเปิดกว้างมากขึ้น บันทึกการแยกโปรเจกต์อย่างเป็นทางการอธิบายว่าโปรเจกต์นี้มีพื้นฐานมาจาก Swagger Codegen 2.4.0-SNAPSHOT ดังนั้นทั้งสองจึงมีรากฐานที่ลึกซึ้ง หากคุณกำลังพิจารณาทั้งสองตัวเลือก การวิเคราะห์ ทางเลือก Swagger Codegen จะครอบคลุมความแตกต่างในทางปฏิบัติ
การติดตั้ง OpenAPI Generator
คุณมีเส้นทางการติดตั้งหลักสี่ทาง เลือกอันที่เหมาะกับ stack ของคุณ
npm (ที่นิยมที่สุด)
npm wrapper เป็นจุดเริ่มต้นที่ง่ายที่สุดสำหรับทีมส่วนใหญ่ มันดาวน์โหลดและจัดการ JAR ที่อยู่เบื้องหลังให้คุณ
npm install @openapitools/openapi-generator-cli -g
คุณยังสามารถรันได้โดยไม่ต้องติดตั้งแบบ global:
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
Standalone JAR
OpenAPI Generator เป็นแอปพลิเคชัน Java ดังนั้นคุณสามารถดาวน์โหลด JAR ได้โดยตรงจาก Maven Central และรันด้วย Java วิธีนี้หลีกเลี่ยงการใช้ npm หรือ 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
ตรวจสอบ Maven Central สำหรับหมายเลขเวอร์ชันล่าสุดก่อนดาวน์โหลด
Docker
อิมเมจอย่างเป็นทางการช่วยให้คุณสร้างโค้ดได้โดยไม่ต้องติดตั้งอะไรในเครื่อง โหลดไดเรกทอรีการทำงานของคุณเข้าไปในคอนเทนเนอร์เพื่อให้มันสามารถอ่าน spec ของคุณและเขียนเอาต์พุตกลับออกมาได้
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
การแสดงรายการ generator ที่มีอยู่
ก่อนที่คุณจะสร้างอะไร ให้ดูว่ามี generator อะไรบ้าง generator แต่ละตัวจะกำหนดเป้าหมายที่ภาษาพร้อมเฟรมเวิร์ก เช่น java, python หรือ spring
openapi-generator-cli list
สำหรับการแสดงผลที่กระชับ หนึ่งบรรทัดต่อรายการ ให้ใช้แฟล็กย่อและแยกด้วยเครื่องหมายจุลภาค:
openapi-generator-cli list -s | tr ',' '\n'
รายการนี้จะแยก generator สำหรับไคลเอ็นต์ (สำหรับเรียก API) ออกจาก generator สำหรับเซิร์ฟเวอร์ (สำหรับใช้งาน API) รวมถึง generator สำหรับเอกสารและสคีมา
การสร้าง client SDK
คำสั่งหลักคือ generate มันรับอาร์กิวเมนต์สามตัวที่คุณจะใช้ทุกครั้ง:
-i, --input-specชี้ไปที่ไฟล์ spec หรือ URL ของคุณ-g, --generator-nameเลือก generator ที่จะรัน-o, --outputกำหนดไดเรกทอรีเอาต์พุต
นี่คือ TypeScript client ที่สร้างบน Axios:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
คำสั่งนั้นจะเขียน client แบบมี type ลงใน ./client การดำเนินการแต่ละรายการใน spec ของคุณจะกลายเป็นเมธอด และแต่ละ schema จะกลายเป็นโมเดล
รูปแบบเดียวกันนี้ใช้งานได้กับทุกภาษา เพียงแค่เปลี่ยนชื่อ generator และโฟลเดอร์เอาต์พุต:
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
เนื่องจากโค้ดมาจาก spec เดียวกัน client ทุกตัวจึงมีความสอดคล้องกับสัญญา เมื่อ spec เปลี่ยนไป คุณก็สร้างใหม่และ SDK ของคุณก็จะตามไปด้วย
การสร้าง server stubs
generator ของเซิร์ฟเวอร์จะพลิกทิศทาง แทนที่จะเป็นโค้ดที่เรียก API ของคุณ คุณจะได้โครงสร้างพื้นฐานที่ใช้งาน API นั้น ด้วยการกำหนดเส้นทาง, โมเดลคำขอ และอินเทอร์เฟซตัวจัดการที่เชื่อมต่อกัน คุณเพียงแค่เติมตรรกะทางธุรกิจเข้าไป
นี่คือ server stub ของ Spring Boot:
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
โปรเจกต์ที่สร้างขึ้นจะให้ controllers และ DTOs ที่ตรงกับ spec ของคุณ คุณใช้งานเมธอดอินเทอร์เฟซ และรูปร่างของคำขอและคำตอบก็ถูกกำหนดไว้ให้คุณแล้ว สิ่งนี้ทำให้เซิร์ฟเวอร์ที่ทำงานอยู่สอดคล้องกับสัญญาที่เผยแพร่
การกำหนดค่าเอาต์พุต
เอาต์พุตเริ่มต้นไม่ค่อยตรงตามที่คุณต้องการทุกประการ OpenAPI Generator ให้การควบคุมหลายอย่างแก่คุณ
คุณสมบัติเพิ่มเติม
generator ส่วนใหญ่จะเปิดเผยตัวเลือกเฉพาะภาษาผ่าน --additional-properties (ชื่อย่อ -p) ส่งค่าเหล่านี้เป็นคู่ key=value ที่คั่นด้วยเครื่องหมายจุลภาค:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
generator แต่ละตัวมีเอกสารคุณสมบัติของตัวเอง ดังนั้นตรวจสอบหน้า generator สำหรับรายการคีย์ทั้งหมดที่ยอมรับ
ไฟล์การกำหนดค่า
เมื่อบรรทัดคำสั่งยาวเกินไป ให้ย้ายตัวเลือกไปยังไฟล์การกำหนดค่า รองรับทั้ง JSON และ YAML
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
ไฟล์การกำหนดค่าจะเก็บการตั้งค่าการสร้างของคุณไว้ในระบบควบคุมเวอร์ชันถัดจาก spec ซึ่งทำให้การสร้างสามารถทำซ้ำได้
การละเว้นไฟล์
OpenAPI Generator จะอ่านไฟล์ .openapi-generator-ignore ในไดเรกทอรีเอาต์พุต มันใช้ไวยากรณ์เดียวกันกับ .gitignore ใช้มันเพื่อป้องกันไม่ให้ generator เขียนทับไฟล์ที่คุณแก้ไขด้วยมือ
# .openapi-generator-ignore
*.md
src/custom/**
คุณสามารถชี้ไปที่ไฟล์ ignore ในตำแหน่งอื่นได้ด้วย --ignore-file-override <location>
เทมเพลตที่กำหนดเอง
generator ทุกตัวขับเคลื่อนด้วยเทมเพลต Mustache หากเอาต์พุตเริ่มต้นไม่ตรงกับสไตล์องค์กรของคุณ ให้คัดลอกเทมเพลต แก้ไข และส่งไดเรกทอรีของคุณด้วย -t:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
นี่เป็นเครื่องมือที่เหมาะสมเมื่อคุณต้องการส่วนหัวที่กำหนดเอง, HTTP client ที่แตกต่างกัน หรือข้อตกลงการตั้งชื่อภายในองค์กรที่ฝังอยู่ในไฟล์ที่สร้างขึ้นทุกไฟล์
การรันใน CI
การสร้างโค้ดควรอยู่ใน pipeline ของคุณ ไม่ใช่อยู่ในแล็ปท็อปของนักพัฒนาคนเดียว สร้าง client ใหม่ทุกครั้งที่ spec เปลี่ยนแปลงเพื่อให้ SDK ที่ commit แล้วไม่คลาดเคลื่อนจากสัญญา นี่คือขั้นตอน GitHub Actions โดยใช้ npx:
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
คุณสามารถทำให้ build ล้มเหลวได้หากเอาต์พุตที่สร้างใหม่แตกต่างจากที่ commit ไว้ ซึ่งจะช่วยตรวจจับ specs และ SDKs ที่ไม่ตรงกัน
เก็บ spec เป็นแหล่งความจริงเดียวของคุณ
OpenAPI Generator จะดีได้ก็ต่อเมื่อ spec ที่คุณป้อนให้มันดีเท่านั้น ขยะเข้าขยะออก: spec ที่คลุมเครือหรือไม่ถูกต้องจะสร้าง SDK ที่คลุมเครือหรือใช้งานไม่ได้ ดังนั้นขั้นตอนที่มีค่าที่สุดจึงเกิดขึ้นก่อนที่คุณจะรัน generate คุณต้องทำให้ spec ถูกต้อง สมบูรณ์ และเสถียร
นี่คือจุดที่ Apidog เข้ามามีบทบาท Apidog เป็นแพลตฟอร์ม API แบบ all-in-one ที่เป็น OpenAPI-native ดังนั้นงานออกแบบของคุณและ spec ของคุณจึงเป็นสิ่งเดียวกัน คุณออกแบบหรือนำเข้า API และ Apidog จะเก็บเอกสาร OpenAPI เป็นแหล่งความจริงที่ทุกสิ่งไหลมาจาก
ขั้นตอนการทำงานที่สะอาดมีดังนี้:
- ออกแบบหรือนำเข้า OpenAPI spec ใน Apidog การรองรับ Branch ช่วยให้คุณทำงานกับการเปลี่ยนแปลงได้โดยอิสระ คล้ายกับการ ควบคุมเวอร์ชัน OpenAPI ด้วย Git
- ตรวจสอบและ lint spec ก่อนที่คุณจะสร้าง spec ที่ผ่าน OpenAPI linter และ Swagger validator จะสร้างโค้ดที่สะอาดขึ้นโดยมีข้อผิดพลาดน้อยลง
- ส่งออก spec ที่ผ่านการตรวจสอบแล้ว จากนั้นป้อนให้กับ OpenAPI Generator สำหรับ SDKs และ stubs ของคุณ
คุณยังสามารถซิงค์ spec กับ repo ของคุณได้ เช่น โดยการ ซิงค์ OpenAPI spec ไปยัง GitHub และตรวจสอบการเปลี่ยนแปลงด้วย OpenAPI diff ก่อนที่จะเผยแพร่ หากคุณกำลังเปลี่ยนจากเครื่องมือเก่าๆ การเปรียบเทียบ ทางเลือก Swagger สำหรับการออกแบบและการทดสอบ API เป็นจุดเริ่มต้นที่ดี
Apidog สิ้นสุดที่ใดและ OpenAPI Generator เริ่มต้นที่ใด
ควรจะกล่าวให้แม่นยำในที่นี้ Apidog ไม่ได้สร้าง client SDKs หรือ server stubs แบบเต็ม นั่นเป็นงานของ OpenAPI Generator และทั้งสองเป็นส่วนเติมเต็มกันมากกว่าที่จะแข่งขันกัน
Apidog ให้สคริปต์คำขอ client ที่พร้อมคัดลอกสำหรับแต่ละ endpoint ในหลายภาษาและ HTTP client สิ่งเหล่านี้เป็นตัวอย่างต่อคำขอที่คุณสามารถวางลงในสคริปต์ ไม่ใช่ SDK ที่เป็นแพ็กเกจ สำหรับไลบรารีที่มีเวอร์ชันหรือโครงสร้างเซิร์ฟเวอร์ที่สร้างขึ้น คุณจะรัน OpenAPI Generator บน spec ที่ Apidog สร้างขึ้น
Apidog ยังมาพร้อมกับ test runner แบบ command-line ของตัวเอง ซึ่งคือ Apidog CLI ซึ่งแยกจากการสร้างโค้ด มันรันการทดสอบ API ของคุณใน CI; มันไม่ได้สร้าง SDKs ติดตั้งและใช้งานได้ดังนี้:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
คุณส่งการยืนยันตัวตนด้วย --access-token, -t เลือก test scenario, -e เลือกสภาพแวดล้อมที่จะรัน และ -r เลือก reporters รันบน Node.js LTS release ปัจจุบัน สำหรับรายละเอียดการตั้งค่า โปรดดู คู่มือการติดตั้ง Apidog CLI และคำแนะนำทีละขั้นตอนเกี่ยวกับ การทดสอบ REST API จาก command line
ดังนั้นวงจรทั้งหมดคือ: ออกแบบและตรวจสอบ spec ใน Apidog, สร้าง SDKs และ stubs ด้วย OpenAPI Generator จากนั้นยืนยัน API ที่ทำงานอยู่ด้วย Apidog CLI
ลองใช้ Apidog ฟรี ไม่ต้องใช้บัตรเครดิต
คำถามที่พบบ่อย
OpenAPI Generator คืออะไร?
OpenAPI Generator เป็นเครื่องมือโอเพนซอร์สจากองค์กร OpenAPITools ที่สร้างโค้ดจาก OpenAPI หรือ Swagger spec มันสร้าง client SDKs, server stubs, เอกสารประกอบ และไฟล์กำหนดค่า และรองรับทั้ง OpenAPI v2 และ v3
คุณใช้ OpenAPI Generator อย่างไร?
ติดตั้ง CLI (เช่น npm install @openapitools/openapi-generator-cli -g) จากนั้นรัน generate พร้อมแฟล็กสามตัว: -i สำหรับ spec ของคุณ, -g สำหรับ generator และ -o สำหรับโฟลเดอร์เอาต์พุต รัน openapi-generator-cli list ก่อนเพื่อดู generator ที่มีอยู่ทั้งหมด
OpenAPI Generator ทำงานอย่างไร?
มันแยกวิเคราะห์ spec ของคุณเป็นโมเดลภายใน จากนั้นแสดงผลโมเดลนั้นผ่านเทมเพลต Mustache สำหรับเป้าหมายที่คุณเลือก การดำเนินการแต่ละรายการจะกลายเป็นเมธอดหรือตัวจัดการ และแต่ละ schema จะกลายเป็นโมเดลที่มี type คุณสามารถแทนที่เทมเพลตด้วย -t เพื่อเปลี่ยนเอาต์พุตได้
คุณจะสร้าง client SDK จาก OpenAPI spec ได้อย่างไร?
เลือก client generator และรัน generate ตัวอย่างเช่น openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client จะสร้าง TypeScript client ที่มี type เปลี่ยน typescript-axios เป็น java, python หรือ go เพื่อกำหนดเป้าหมายภาษาอื่นๆ
คุณจะสร้าง server stubs ได้อย่างไร?
เลือก server generator สำหรับโครงสร้าง Spring Boot ให้รัน openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring เอาต์พุตจะรวม controllers และ request models จาก spec ของคุณ และคุณจะต้องใช้ตรรกะของตัวจัดการ
อะไรคือความแตกต่างระหว่าง OpenAPI Generator และ Swagger Codegen?
OpenAPI Generator ถูกแยกออกมาจาก Swagger Codegen ในเดือนพฤษภาคม 2018 โดยผู้มีส่วนร่วมมากกว่า 40 คน ซึ่งต้องการวงจรการเผยแพร่ที่รวดเร็วและขับเคลื่อนโดยชุมชน ทั้งสองมีพื้นฐานร่วมกัน แต่ OpenAPI Generator มีแผนงาน, ชุด generator และกำหนดการเผยแพร่ของตัวเองแล้วในตอนนี้
คุณจะสร้าง PHP SDK จาก OpenAPI spec ได้อย่างไร?
ใช้ php generator: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php รัน openapi-generator-cli list เพื่อยืนยันชื่อ generator ที่แน่นอนและดูตัวเลือก PHP framework อื่นๆ ก่อนที่คุณจะสร้าง