เอกสาร AsyncAPI โดยพื้นฐานแล้ว Web API มีสองประเภท: ซิงโครนัสและอะซิงโครนัส API แบบซิงโครนัสจะส่งคืนข้อมูลในทันที ให้วิธีการดึงข้อมูลแบบทันทีหรือตามกำหนดการ เมื่อใดก็ตามที่คุณเรียกใช้ API แบบซิงโครนัส API นั้นจะถูกบล็อกจนกว่าเซิร์ฟเวอร์จะตอบกลับ แอปพลิเคชันที่ร้องขอข้อมูลจะรอให้ API สร้างการตอบสนอง
ขณะอยู่ใน API แบบอะซิงโครนัส ฟังก์ชันเรียกกลับจะทำงานเมื่อมีการตอบกลับจาก API การเรียก API ไม่ได้บล็อกแอปพลิเคชัน และแอปพลิเคชันไม่รอให้ API ตอบกลับ ดังนั้นจึงยังคงดำเนินการฟังก์ชันอื่นๆ API เหล่านี้มีประโยชน์สำหรับแอปพลิเคชันที่ต้องโหลดส่วนประกอบอื่นๆ ที่ไม่ขึ้นอยู่กับ API
AsyncAPI คืออะไร?
AsyncAPIเป็นคำจำกัดความ API ที่ได้รับการสนับสนุนจากโครงการโอเพ่นซอร์สเพื่อกำหนด API แบบอะซิงโครนัสที่ขับเคลื่อนด้วยเหตุการณ์ เนื่องจากOpenAPIกำหนดรายละเอียดของ REST API AsyncAPI จะกำหนดความซับซ้อนของ API แบบอะซิงโครนัส ข้อกำหนด AsyncAPI ได้รับแรงบันดาลใจจากข้อกำหนดของ OpenAPI (เดิมเรียกว่า Swagger) และอธิบายและจัดทำเอกสาร API แบบอะซิงโครนัสที่ขับเคลื่อนด้วยเหตุการณ์ในรูปแบบที่เครื่องอ่านได้
ตัวอย่างเช่น เมื่อคุณใช้ WebSockets หรือเมื่อบริการที่แตกต่างกันสองรายการคุยกันผ่านตัวรับส่งข้อความ คุณจะไม่สามารถใช้ API แบบซิงโครนัสที่นี่ได้ เนื่องจากจำเป็นต้องมีโฟลว์ข้อมูลแบบสองทิศทาง ซึ่งไม่ได้สื่อสารผ่าน HTTP นี้เรียกว่าระบบฟูลดูเพล็กซ์ที่ไคลเอ็นต์และเซิร์ฟเวอร์เชื่อมต่อกันในลักษณะถาวร ลูกค้าไม่จำเป็นต้อง ping เซิร์ฟเวอร์ซ้ำแล้วซ้ำอีกเพื่อรับข้อมูลใหม่ เมื่อใดก็ตามที่ข้อมูลถูกส่งไปยังเซิร์ฟเวอร์ ข้อมูลจะถูกส่งไปยังไคลเอนต์โดยอัตโนมัติ
นี่คือจุดเริ่มต้นของ AsyncAPI เนื่องจาก OpenAPI รองรับเฉพาะ HTTP API เช่น REST AsyncAPI เหมาะสมอย่างยิ่งกับโปรโตคอล เช่น AMQP, Kafka, MQTT เป็นต้น คุณสามารถดูบทความของเราเกี่ยวกับ7 โปรโตคอลที่ดีสำหรับการจัดทำเอกสารด้วย Async APIซึ่งเราได้พูดถึงโปรโตคอลเหล่านี้โดยละเอียดแล้ว
ทำไมต้องจัดทำเอกสาร API แบบอะซิงโครนัส
เมื่อคุณกำลังสร้างจุดปลาย API ที่แตกต่างกัน จุดจะเกิดขึ้นเมื่อคุณเริ่มลืมชื่อของปลายทาง API เหล่านั้น จากมุมมองทางธุรกิจ คุณไม่ใช่คนเดียวที่จะบริโภคมันใช่ไหม? ดังนั้น แนวทางปฏิบัติที่ดีที่สุดคือการจัดทำเอกสาร API ทั้งหมดที่คุณสร้าง โดยอธิบายแต่ละปลายทางเพื่อช่วยผู้บริโภค API ในอนาคต ซึ่งจะทำให้ API ของคุณเข้าใจง่าย และช่วยให้คุณมุ่งเน้นที่การพัฒนาและปรับปรุงเพิ่มเติม
ประโยชน์อื่นๆ ได้แก่:
- เอกสารประกอบช่วยปรับปรุงอัตราการยอมรับ API
- เอกสารช่วยให้ทีมพัฒนา (และสมาชิกใหม่ในกลุ่ม) เข้าใจ API และวิธีการทำงานได้ง่าย
- เอกสารช่วยประหยัดเวลาและค่าใช้จ่ายสำหรับบริษัทได้มาก
- เอกสารประกอบทำให้การบำรุงรักษา API ง่ายขึ้น
ตัวสร้างเอกสาร Async API ยอดนิยม
หากคุณกำลังใช้ AsyncAPI และต้องการจัดทำเอกสาร API ของคุณ เราพร้อมช่วยคุณแล้ว เราได้รวบรวมรายชื่อตัวสร้างเอกสาร Async API เพื่อช่วย:
วิดเดอร์ชินส์
Widdershins เป็นหนึ่งในเครื่องมือสร้างเอกสารยอดนิยมที่รองรับ AsyncAPI รองรับรูปแบบ HTML และ ReSpec ได้โดยตรงจากกล่อง ส่วนใหญ่จะใช้เป็นขั้นตอนในการจัดทำเอกสาร API ช่วยให้คุณสร้างข้อมูลโค้ดใน NodeJS, JavaScript, Shell, Ruby, Pythonและ Java และเอกสารที่สร้างขึ้นนั้นเป็นมิตรกับอุปกรณ์พกพาทั้งหมด ซึ่งหมายความว่ารองรับขนาดหน้าจอที่แตกต่างกัน หนึ่งในส่วนที่ดีที่สุดของ Widdershins คือมันให้คุณใช้คำสัญญาแทนการโทรกลับ ซึ่งค่อนข้างใหม่ นอกจากนี้ยังรองรับข้อกำหนด API อื่นๆ เช่น Open API 3.0, OpenAPI 2.0, รูปแบบ Semoasa ของ RepreZenและ API Blueprint
Widdershins ใช้เทมเพลตเพื่อสร้างไฟล์ markdown เทมเพลตเหล่านี้ปรับแต่งได้อย่างสมบูรณ์และจัดการได้ง่ายมาก บริษัทบางแห่งที่ใช้ Widdershins ได้แก่ Shutterstock, Capital One, Open EO และอื่นๆ
- คำสั่งในการติดตั้ง WidderShins:
npm install -g widdershins - ดูตัวอย่างแบบสด: https://api-reference.shutterstock.com/#overview
เครื่องกำเนิดไฟฟ้า
เครื่องมือสร้างเป็นหนึ่งในตัวเลือกเอกสาร Async API ที่ดีที่สุด ตามเว็บไซต์ของพวกเขา มันช่วยให้คุณสร้างสิ่งที่คุณต้องการ ความหมายจริงๆ ก็คือ คุณสามารถสร้างเอกสาร HTML, โค้ด NodeJS และเอกสาร Markdown ได้ ใช้ระบบเทมเพลตเพื่อสร้างเอกสารสำหรับ API ในการสร้างเอกสาร API คุณจะต้องสร้างเทมเพลตแล้วใช้เทมเพลตนั้นเพื่อสร้างหน้า มีเทมเพลตที่สร้างไว้ล่วงหน้าไม่กี่แบบสำหรับเครื่องมือสร้าง เช่นasyncapi/nodejs-template, asyncapi/nodejs-ws-template, asyncapi/java-spring-template ฯลฯ
- คำสั่งในการติดตั้ง Generator:
npm install -g @asyncapi/generator
api2html
api2html เป็นเครื่องมือ CLI ที่ใช้สร้างเอกสาร AsyncAPI โดยใช้ข้อมูลดิบ API รองรับคำจำกัดความ API ต่างๆ เช่น Open API, AsyncAPI และ Swagger และสร้างเอกสาร HTML ตัวสร้างเอกสารรองรับ 33 ภาษา (ไม่ใช่ภาษาการเขียนโปรแกรม) และสามารถให้บริการเพจแบบสแตติกและไดนามิก หนึ่งในส่วนที่ดีที่สุดของ api2html คือมันใช้Cache-Controlส่วนหัวเพื่อส่งคำขอ API ดังนั้น หากคุณส่งคำขอ API ใดๆ ผ่าน api2html มันจะบันทึกการตอบสนองของแคชในช่วงระยะเวลาหนึ่ง การใช้ทรัพยากรของเครื่องสร้างเอกสารนี้ต่ำมาก (ประมาณ 15MB) ดังนั้นคุณจึงไม่ต้องกังวลว่าเซิร์ฟเวอร์จะขัดข้องหากคุณโฮสต์ไว้บนเซิร์ฟเวอร์เดียวกันกับ API
- คำสั่งในการติดตั้ง api2html:
npm i api2html -g - ดูตัวอย่างสด: https://tobilg.github.io/api2html/petstore/#swagger-petstore
ชน
Bump เป็นเครื่องมือสร้างเอกสาร Async อีกตัวที่ใช้ GitHub Actions เพื่อสร้างและซิงโครไนซ์เอกสารกับ API โดยอัตโนมัติ รองรับคำจำกัดความ OpenAPI และ AsyncAPI คุณอาจสงสัยว่า GitHub Actions คืออะไร? พวกมันถูกใช้เพื่อทำให้เวิร์กโฟลว์การพัฒนาซอฟต์แวร์เป็นแบบอัตโนมัติ สิ่งนี้ช่วยให้คุณสร้าง ทดสอบ ปรับใช้โค้ดของคุณบน GitHub และติดตามการเปลี่ยนแปลงโค้ด UI ของเครื่องมือเอกสารนั้นสะอาดมากและทำหน้าที่เป็นแอปพลิเคชันหน้าเดียว
- ดาวน์โหลด Bump: https://bump.sh/
- ดูตัวอย่างสด: https://docs.canopyservicing.com/
สปริงวูล์ฟ
Springwolf เป็นเครื่องมือสร้างเอกสาร Async API ที่ได้รับแรงบันดาลใจจาก SpringFox ซึ่งเป็นตัวสร้างเอกสาร API อื่นสำหรับ REST APIs ตาม Spring และ JSON SpringWolf ใช้เพื่อสร้างเอกสาร API ตาม Spring Boot และเป็นไปตามข้อกำหนด AsyncAPI มันสร้างเอกสาร API ซึ่งมีตัวอย่างส่วนของข้อมูลที่สร้างขึ้นโดยอัตโนมัติและ UI ที่ปรับแต่งได้ง่าย สามารถสร้างเอกสาร API ได้โดยอัตโนมัติโดยใช้คำอธิบายประกอบของ Listener เช่น@kafkalistener. เอกสาร API นี้มีประโยชน์สำหรับผู้บริโภค Kafka
- คำสั่งติดตั้ง SpringWolf:
git clone https://github.com/springwolf/springwolf-core.git - คุณยังสามารถตรวจสอบการแสดงตัวอย่างสดได้ที่: https://springwolf.github.io/springwolf-ui/
เซาเตอร์
Saunter เป็นเครื่องมือสร้างเอกสาร API อีกตัวที่ใช้สำหรับ .NET API ปัจจุบัน Saunter รองรับการเชื่อมโยง HTTP และ Kafka ตัวสร้างเอกสาร AsyncAPI นี้ได้รับแรงบันดาลใจจาก Swashbuckle ซึ่งเป็นตัวสร้างเอกสาร .NET API อื่น แต่สำหรับ REST API
- คำสั่งในการติดตั้ง Saunter:
dotnet add package Saunter - สามารถชมตัวอย่างสดได้ที่: https://github.com/tehmantra/saunter
อาลักษณ์
Scribano ใช้เพื่อสร้างเอกสารสำหรับ AsyncAPIs ที่ใช้ RabbitMQ มันติดตามข้อความทั้งหมดที่ได้รับและส่งโดยใช้ RabbitMQ และคอยอัปเดต API ตามคำจำกัดความ AsyncAPI ที่ให้บริการ/asyncapiที่ RabbitMQ คือการแลกเปลี่ยนข้อความ และ Scribano ได้รับข้อความทั้งหมดจากมัน หลังจากได้รับข้อความ จะสร้างและให้บริการเอกสารที่/asyncapiเส้นทาง
- คำสั่งในการติดตั้ง Scribano:
git clone https://github.com/uesteibar/scribano.git
AsyncAPI React
AsyncAPI React เป็นส่วนประกอบ ReactJS อย่างเป็นทางการสำหรับการบันทึก AsyncAPI คุณสามารถรวมส่วนประกอบ React แบบกำหนดเองของคุณในเครื่องมือสร้างเอกสารนี้เพื่อให้ดูสวยงามยิ่งขึ้น AsyncAPI React มาพร้อมกับ Playground Application ที่ให้คุณทดสอบ APIได้ทุกที่ นอกจากนี้ยังช่วยให้คุณใช้ส่วนประกอบเชิงมุมเพื่อทำการเปลี่ยนแปลงการปรับแต่งเพิ่มเติมได้
- คำสั่งในการติดตั้ง AsyncAPI React:
npm install --save @asyncapi/react-component - คุณยังสามารถตรวจสอบการแสดงตัวอย่างสดได้ที่: https://asyncapi.github.io/asyncapi-react/
การยกย่องชมเชย
เราออกจากตัวสร้างเอกสาร AsyncAPI หรือไม่ แสดงความคิดเห็นด้านล่าง แล้วเราจะพิจารณาเพิ่มลงในรายการของเรา!
คำพูดสุดท้าย
ในบทความนี้ เราพยายามรวมโซลูชันเอกสาร AsyncAPI ที่ดีที่สุดเพื่อสร้างเอกสารสำหรับ API แบบอะซิงโครนัสของคุณ ทุกคนมีข้อกำหนดที่แตกต่างกัน และเครื่องมือสร้างเอกสารเหล่านี้ก็สามารถตอบสนองความต้องการเหล่านั้นได้ เครื่องมือเอกสาร API เหล่านี้บางส่วนสามารถช่วยให้คุณเรียกใช้ API ของคุณได้ทุกที่ ดังนั้นมันจึงขึ้นอยู่กับความต้องการของคุณและเป้าหมายสุดท้ายที่คุณต้องการบรรลุด้วยเครื่องมือเหล่านี้ เรายังได้กล่าวถึงเครื่องมือจัดทำเอกสาร OpenAPI V3 ที่ดีที่สุดด้วย — ตรวจสอบว่าคุณต้องการจัดทำเอกสาร REST API ของคุณ
ทั้งนี้บริษัทเคแอนด์โอ จึงได้มุ่งเน้นการจัดการแก้ไขปัญหา จัดการเอกสาร ด้านเอกสารขององค์กรมาอย่างยาวนาน และ ให้ความสำคัญกับด้านงานเอกสาร ต่อลูกค้าเป็นอย่างดี จนถึงปัจจุบันก็ได้ความยอมรับจากองค์กร ขนาดใหญ่ ขนาดกลาง และขนาดเล็กมากมาย จึงใคร่ขออาสาดูและปัญหาด้านเอกสารให้กับองค์กรของท่านอย่างสุดความสามารถ เพราะเราเป็นหนึ่งในธุรกิจ ระบบจัดเก็บเอกสาร ที่ท่านไว้ใจได้
สอบถามได้สบายใจทั้ง เรื่องค่าบริการ ราคา และ งบประมาณ เพราะเป็นราคาที่สุด คุ้มที่สุด
เรามีแอดมินคอยคอบคำถาม 24 ชั้วโมงที่ Line OA ให้คำปรึกษาด้านวางระบบจัดการเอกสารอิเล็กทรอนิกส์ EDMS โดยทีมงานผู้เชี่ยวชาญจาก K&O
ที่มีประสบการณ์มากว่า 15 ปี รวมถึงซอฟต์แวร์ระดับโลก ติดต่อ 0 2 – 8 6 0 – 6 6 5 9 หรือ E m a i l : c s @ k o . i n . t h
หากท่านมีความสนใจ บทความ หรือ Technology สามารถติดต่อได้ตามเบอร์ที่ให้ไว้ด้านล่างนี้
Tel.086-594-5494
Tel.095-919-6699
