swagger codegen
Swagger
นี่คือโปรเจ็กต์ Swagger Codegen ซึ่งอนุญาตให้สร้างไลบรารีไคลเอนต์ API (การสร้าง SDK) สตับเซิร์ฟเวอร์ และเอกสารประกอบที่ได้รับข้อมูลจำเพาะของ OpenAPI โดยอัตโนมัติ
หากคุณต้องการมีส่วนร่วม โปรดดูหลักเกณฑ์และรายการงานที่เปิดอยู่
สำหรับข้อมูลเพิ่มเติม โปรดดูที่หน้า Wiki และ FAQ ?
เอกสารนี้อ้างอิงถึงเวอร์ชัน 2.X ตรวจสอบที่นี่สำหรับ 3.X
Swagger Codegen ทั้งเวอร์ชัน 2.X และ 3.X พร้อมใช้งานและได้รับการดูแลอย่างแยกจากกัน
หมายเหตุ:
เวอร์ชัน 2.X ( io.swagger ) และ 3.X ( io.swagger.codegen.v3 ) มีรหัสกลุ่ม ที่แตกต่างกัน
OpenAPI 3.0.X รองรับเฉพาะเวอร์ชัน 3.X เท่านั้น
สำหรับข้อมูลเวอร์ชันเต็ม โปรดดูเอกสารประกอบเวอร์ชัน
ปัจจุบันรองรับภาษา/เฟรมเวิร์กต่อไปนี้:
ไคลเอนต์ API : ActionScript , Ada , Apex , Bash , C# (.net 2.0, 3.5 หรือใหม่กว่า), C++ (cpprest, Qt5, Tizen), Clojure , Dart , Elixir , Elm , Eiffel , Erlang , Go , Groovy , Haskell (http - ลูกค้า, คนรับใช้), ชวา (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, ไลบรารีไคลเอ็นต์ Google API สำหรับ Java, มั่นใจได้), Kotlin , Lua , Node.js (ES5, ES6, AngularJS พร้อมด้วยคำอธิบายประกอบของ Google Closed Compiler) Objective-C , Perl , PHP , PowerShell , Python , R , Ruby , Rust (สนิม, สนิมเซิร์ฟเวอร์), Scala (akka, http4s, ผยอง-async-httpclient), Swift (2.x, 3.x, 4.x, 5.x), typescript (Angular1.x, Angular2.x, ดึงข้อมูล, jQuery, โหนด)
สตับเซิร์ฟเวอร์ : Ada , C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang , Go , Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy , Play Framework, PKMST), Kotlin , PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS , Ruby (Sinatra, Rails5), Rust (เซิร์ฟเวอร์สนิม), Scala (Finch, Lagom, Scalatra)
ตัวสร้างเอกสาร API : HTML , Confluence Wiki
ไฟล์คอนฟิกูเรชัน : Apache2
อื่นๆ : JMeter
ตรวจสอบ OpenAPI-Spec เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับโปรเจ็กต์ OpenAPI
การกำหนดเวอร์ชัน
ความเข้ากันได้
เริ่มต้นใช้งาน
เครื่องกำเนิดไฟฟ้า
เพื่อสร้างไลบรารีไคลเอนต์ตัวอย่าง
การสร้างไลบรารีจากเซิร์ฟเวอร์ของคุณ
กำลังตรวจสอบข้อมูลจำเพาะ OpenAPI ของคุณ
การสร้างเอกสาร html api แบบไดนามิก
การสร้างเอกสาร html api แบบคงที่
บูรณาการขั้นตอนการทำงาน
เครื่องกำเนิดไฟฟ้าออนไลน์
ผลงาน
ทีมหลักสแวกเกอร์ โคเดเจน
ข้อมูลจำเพาะของ OpenAPI ได้รับการปรับปรุง 3 ครั้งนับตั้งแต่การสร้างครั้งแรกในปี 2010 โปรเจ็กต์ Swagger Codegen เวอร์ชัน เสถียรในปัจจุบัน มีความเข้ากันได้กับข้อกำหนด OpenAPI ดังต่อไปนี้:
| เวอร์ชั่น Swagger Codegen | วันที่วางจำหน่าย | ความเข้ากันได้ของ Swagger / OpenAPI Spec | หมายเหตุ |
|---|---|---|---|
| 3.0.62 ( ปัจจุบันมีเสถียรภาพ ) | 27-08-2024 | 1.0, 1.1, 1.2, 2.0, 3.0 | แท็ก v3.0.62 |
| 2.4.43 ( ปัจจุบันมีเสถียรภาพ ) | 09-08-2024 | 1.0, 1.1, 1.2, 2.0 | แท็ก v2.4.42 |
ต่อไปนี้เป็นภาพรวมของสิ่งที่จะเกิดขึ้นเร็วๆ นี้:
| เวอร์ชั่น Swagger Codegen | วันที่วางจำหน่าย | ความเข้ากันได้ของ Swagger / OpenAPI Spec | หมายเหตุ |
|---|---|---|---|
| 3.0.63-SNAPSHOT (ปัจจุบัน 3.0.0, รุ่นรองที่กำลังจะเปิดตัว) SNAPSHOT | จะแจ้งภายหลัง | 1.0, 1.1, 1.2, 2.0, 3.0 | การปล่อยเล็กน้อย |
| 2.4.44-SNAPSHOT (ต้นแบบปัจจุบัน รุ่นรองที่กำลังจะเปิดตัว) SNAPSHOT | จะแจ้งภายหลัง | 1.0, 1.1, 1.2, 2.0 | การปล่อยเล็กน้อย |
สำหรับรายละเอียดโดยละเอียดของทุกรุ่น โปรดดูรายการความเข้ากันได้ทั้งหมด
หากต้องการเริ่มต้นใช้งาน Swagger Codegen โปรดดูคำแนะนำและคำแนะนำต่อไปนี้:
ข้อกำหนดเบื้องต้น
อาคาร
การใช้นักเทียบท่า
เมื่อคุณตั้งค่าสภาพแวดล้อมแล้ว คุณก็พร้อมที่จะเริ่มสร้างไคลเอนต์และ/หรือเซิร์ฟเวอร์แล้ว
เพื่อเป็นตัวอย่างอย่างรวดเร็ว หากต้องการสร้างไคลเอ็นต์ PHP สำหรับ https://petstore.swagger.io/v2/swagger.json คุณสามารถเรียกใช้สิ่งต่อไปนี้:
โคลนคอมไพล์ https://github.com/swagger-api/swagger-codegencd swagger-codegen
mvn แพ็คเกจที่สะอาด
โมดูล java -jar/swagger-codegen-cli/target/swagger-codegen-cli.jar สร้าง
-i https://petstore.swagger.io/v2/swagger.json
-l.php
-o /var/tmp/php_api_clientหมายเหตุ: หากคุณใช้ Windows ให้แทนที่คำสั่งสุดท้ายด้วย
java -jar modulesswagger-codegen-clitargetswagger-codegen-cli.jar สร้าง -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
คุณยังสามารถดาวน์โหลด JAR (รุ่นล่าสุด) ได้โดยตรงจาก maven.org
หากต้องการรับรายการตัวเลือก ทั่วไป ที่มีให้ คุณสามารถเรียกใช้สิ่งต่อไปนี้:
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar ช่วยสร้าง
หากต้องการรับรายการตัวเลือกที่ระบุ PHP (ซึ่งสามารถส่งผ่านไปยังตัวสร้างด้วยไฟล์ปรับแต่งผ่านตัวเลือก -c ) โปรดเรียกใช้
โมดูล java -jar/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
คุณสามารถสร้างไคลเอนต์โดยเทียบกับ API ของ petstore ตัวอย่างผยองได้ดังต่อไปนี้:
./bin/java-petstore.sh
(บน Windows ให้เรียกใช้ .binwindowsjava-petstore.bat แทน)
สิ่งนี้จะรันตัวสร้างด้วยคำสั่งนี้:
โมดูล java -jar/swagger-codegen-cli/target/swagger-codegen-cli.jar สร้าง -i https://petstore.swagger.io/v2/swagger.json -l ชวา -o ตัวอย่าง/ไคลเอนต์/ร้านขายสัตว์เลี้ยง/java
พร้อมตัวเลือกมากมาย คุณสามารถรับตัวเลือกต่างๆ ได้ด้วยคำสั่ง help generate (ด้านล่างแสดงเฉพาะผลลัพธ์บางส่วนเท่านั้น):
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate
[(-a <authorization> | --auth <authorization>)]
[--additional-properties <additional properties>...]
[--api-package <api package>] [--artifact-id <artifact id>]
[--artifact-version <artifact version>]
[(-c <configuration file> | --config <configuration file>)]
[-D <system properties>...] [--git-repo-id <git repo id>]
[--git-user-id <git user id>] [--group-id <group id>]
[--http-user-agent <http user agent>]
(-i <spec file> | --input-spec <spec file>)
[--ignore-file-override <ignore file override location>]
[--import-mappings <import mappings>...]
[--instantiation-types <instantiation types>...]
[--invoker-package <invoker package>]
(-l <language> | --lang <language>)
[--language-specific-primitives <language specific primitives>...]
[--library <library>] [--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[--model-package <model package>]
[(-o <output directory> | --output <output directory>)]
[--release-note <release note>] [--remove-operation-id-prefix]
[--reserved-words-mappings <reserved word mappings>...]
[(-s | --skip-overwrite)]
[(-t <template directory> | --template-dir <template directory>)]
[--type-mappings <type mappings>...] [(-v | --verbose)]
OPTIONS
-a <authorization>, --auth <authorization>
adds authorization headers when fetching the swagger definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
...... (results omitted)
-v, --verbose
verbose modeจากนั้นคุณสามารถคอมไพล์และรันไคลเอนต์ รวมถึงการทดสอบหน่วยกับไคลเอนต์ได้:
ตัวอย่างซีดี/ไคลเอนต์/petstore/java.cd แพ็คเกจเอ็มวีเอ็น
ภาษาอื่นๆ มีตัวอย่างร้านขายสัตว์เลี้ยงด้วย:
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
ง่ายดายไม่แพ้กัน เพียงใช้แฟล็ก -i เพื่อชี้ไปที่เซิร์ฟเวอร์หรือไฟล์
- Swagger Codegen มาพร้อมกับความยืดหยุ่นมากมายเพื่อรองรับการตั้งค่าการสร้างโค้ดของคุณ ชำระเงินเอกสารประกอบของเครื่องกำเนิดไฟฟ้าซึ่งจะพาคุณผ่านความเป็นไปได้บางประการ พร้อมทั้งแสดงวิธีการสร้างจากไฟล์ในเครื่องและละเว้นรูปแบบไฟล์
คุณอาจไม่ต้องการสร้างแบบจำลอง ทั้งหมด ในโครงการของคุณ ในทำนองเดียวกันคุณอาจต้องการเขียน apis เพียงหนึ่งหรือสองตัว หากเป็นกรณีนี้ ให้ตรวจสอบคำแนะนำในการสร้างแบบเลือกสรร
การปรับแต่งตัวสร้างโค้ดมีแง่มุมต่างๆ มากมาย นอกเหนือจากการสร้างหรือแก้ไขเทมเพลต แต่ละภาษามีไฟล์การกำหนดค่าที่รองรับเพื่อจัดการการแมปประเภทต่างๆ หรือนำโมเดลของคุณเองมาด้วย สำหรับข้อมูลเพิ่มเติม โปรดดูเอกสารการกำหนดค่าขั้นสูง
คุณมีตัวเลือก วิธีที่ง่ายที่สุดคือการใช้เครื่องมือตรวจสอบออนไลน์ของเรา ซึ่งไม่เพียงแต่จะช่วยให้คุณตรวจสอบข้อมูลจำเพาะของคุณเท่านั้น แต่ด้วยสถานะการแก้ไขข้อบกพร่อง คุณสามารถดูได้ว่ามีอะไรผิดปกติกับข้อมูลจำเพาะของคุณ ตัวอย่างเช่น ตรวจสอบ Swagger Validator
หากคุณต้องการให้มีการตรวจสอบโดยตรงบนเครื่องของคุณเอง Spectral เป็นตัวเลือกที่ยอดเยี่ยม
ในการทำเช่นนั้น เพียงใช้แฟล็ก -l dynamic-html เมื่ออ่านไฟล์ข้อมูลจำเพาะ สิ่งนี้จะสร้างเอกสาร HTML ที่พร้อมใช้งานเป็นแอปพลิเคชันหน้าเดียวด้วย AJAX หากต้องการดูเอกสาร:
ตัวอย่างซีดี/ไดนามิก-html/ ติดตั้ง npm โหนด
ซึ่งเปิดตัวเซิร์ฟเวอร์ node.js ดังนั้นการโทร AJAX จึงมีที่ไป
ในการทำเช่นนั้น เพียงใช้แฟล็ก -l html เมื่ออ่านไฟล์ข้อมูลจำเพาะ ซึ่งจะสร้างไฟล์ HTML ธรรมดาไฟล์เดียวที่มี css ฝังอยู่ เพื่อให้คุณสามารถจัดส่งเป็นไฟล์แนบในอีเมล หรือโหลดจากระบบไฟล์ของคุณ:
ตัวอย่างซีดี/html/ เปิดดัชนี.html
คุณสามารถใช้ประโยชน์จาก Swagger Codegen ได้โดยตรงภายในเวิร์กโฟลว์ CI/CD ที่คุณต้องการ เพื่อปรับปรุงข้อกำหนดในการสร้างอัตโนมัติของคุณ ดูคู่มือการรวมเวิร์กโฟลว์เพื่อดูข้อมูลเกี่ยวกับตัวเลือกการรวม Maven, Gradle และ GitHub ของเรา -
หากคุณไม่ต้องการรันและโฮสต์อินสแตนซ์การสร้างโค้ดของคุณเอง โปรดตรวจสอบข้อมูลตัวสร้างออนไลน์ของเรา
โปรดดูที่หน้านี้
สมาชิกในทีมหลักของ Swagger Codegen คือผู้มีส่วนร่วมที่มีส่วนสำคัญ (ตรวจสอบปัญหา แก้ไขข้อบกพร่อง ปรับปรุง ฯลฯ) ให้กับโปรเจ็กต์เป็นประจำ
สมาชิกในทีมหลักมีหน้าที่รับผิดชอบดังต่อไปนี้:
ให้คำแนะนำและทิศทางแก่ผู้ใช้รายอื่น
รีวิวดึงคำขอและปัญหา
ปรับปรุงตัวสร้างโดยการปรับปรุง แก้ไขจุดบกพร่อง หรืออัปเดตเอกสารประกอบ
กำหนดทิศทางทางเทคนิคของเครื่องกำเนิดไฟฟ้า
โปรดเปิดเผยปัญหาหรือช่องโหว่ด้านความปลอดภัยโดยส่งอีเมลไปที่ [email protected] แทนที่จะใช้เครื่องมือติดตามปัญหาสาธารณะ
โปรเจ็กต์ Swagger Codegen มีวัตถุประสงค์เพื่อเป็นประโยชน์สำหรับผู้ใช้ข้อกำหนด Swagger / Open API ตัวโครงการเองมีใบอนุญาตตามที่ระบุไว้ นอกจากนี้ โปรดทำความเข้าใจประเด็นต่อไปนี้:
เทมเพลตที่มาพร้อมกับโปรเจ็กต์นี้อยู่ภายใต้ใบอนุญาต
รหัสที่สร้างขึ้นนั้น ไม่ได้ ตั้งใจให้อยู่ภายใต้ใบอนุญาตของโครงการหลัก
เมื่อโค้ดถูกสร้างขึ้นจากโปรเจ็กต์นี้จะถือว่าเป็น ไปตามสภาพ และเป็นของผู้ใช้ซอฟต์แวร์ ไม่มีการรับประกันทั้งโดยชัดแจ้งหรือโดยนัยสำหรับโค้ดที่สร้างขึ้น คุณสามารถทำสิ่งที่คุณต้องการได้ และเมื่อสร้างขึ้นแล้ว รหัสจะเป็นความรับผิดชอบของคุณและอยู่ภายใต้เงื่อนไขการอนุญาตสิทธิ์ที่คุณเห็นว่าเหมาะสม
เราอยากจะส่งเสียงเชียร์ให้กับทุกคนที่มีส่วนร่วมใน Swagger Codegen ไม่ว่าจะเป็นการหยิบยกปัญหา การแก้ไขข้อบกพร่อง การสร้างเทมเพลต หรือการสร้างเนื้อหาที่เป็นประโยชน์เพื่อให้ผู้อื่นได้รับประโยชน์
