RAML หรือ OAS (Swagger) คืออะไร?

ในโลกแบบไดนามิกของไมโครเซอร์วิส ทุกสิ่งสามารถเปลี่ยนแปลงได้ ส่วนประกอบใดๆ สามารถเขียนใหม่ในภาษาอื่นได้ โดยใช้เฟรมเวิร์กและสถาปัตยกรรมที่แตกต่างกัน สัญญาเท่านั้นที่ควรยังคงไม่เปลี่ยนแปลงเพื่อให้สามารถโต้ตอบกับไมโครเซอร์วิสจากภายนอกได้อย่างถาวร โดยไม่คำนึงถึงการเปลี่ยนแปลงภายใน และวันนี้เราจะพูดถึงปัญหาในการเลือกรูปแบบในการอธิบายสัญญาและแบ่งปันสิ่งประดิษฐ์ที่เราพบ

โพสเตรียมไว้แล้ว แอนนา เมเลโควา и วลาดิเมียร์ ลาปาติน

ไมโครเซอร์วิส เมื่อพัฒนา Acronis Cyber ​​Cloud เราก็ตระหนักได้ว่าเราไม่สามารถหลีกหนีจากสิ่งเหล่านี้ได้ และการออกแบบไมโครเซอร์วิสนั้นเป็นไปไม่ได้หากปราศจากการทำสัญญาอย่างเป็นทางการ ซึ่งแสดงถึงอินเทอร์เฟซของไมโครเซอร์วิส

แต่เมื่อผลิตภัณฑ์มีส่วนประกอบมากกว่าหนึ่งองค์ประกอบ และการพัฒนาตามสัญญากลายเป็นกิจกรรมปกติ คุณอดไม่ได้ที่จะเริ่มต้นคิดถึงการปรับกระบวนการให้เหมาะสมที่สุด เห็นได้ชัดว่าอินเทอร์เฟซ (สัญญา) และการใช้งาน (ไมโครเซอร์วิส) จะต้องตรงกัน ส่วนประกอบที่แตกต่างกันต้องทำสิ่งเดียวกันในลักษณะเดียวกัน และหากไม่มีการตัดสินใจแบบรวมศูนย์สำหรับการตัดสินใจทั้งหมดนี้ แต่ละทีมจะถูกบังคับให้ ใช้เวลาครั้งแล้วครั้งเล่าเพื่อให้ได้มา

ไดอะแกรมไมโครเซอร์วิสของ Amazon จาก ทวีต เวอร์เนอร์ โวเกลิส ซีทีโอของ Amazon
ภาวะที่กลืนไม่เข้าคายไม่ออกคืออะไร? โดยพฤตินัย มีสองวิธีในการโต้ตอบไมโครเซอร์วิส - HTTP Rest และ gRPC จาก Google ด้วยความไม่ต้องการจมอยู่กับกลุ่มเทคโนโลยีของ Google เราจึงเลือก HTTP Rest คำอธิบายประกอบสัญญา HTTP REST มักอธิบายไว้ในหนึ่งในสองรูปแบบ: RAML และ OAS ซึ่งเดิมเรียกว่า Swagger ดังนั้น ทีมพัฒนาทุกทีมจึงต้องเผชิญกับความจำเป็นในการเลือกหนึ่งในมาตรฐาน แต่ปรากฎว่าการตัดสินใจเลือกนี้อาจเป็นเรื่องยากมาก

เหตุใดจึงต้องมีคำอธิบายประกอบ?

จำเป็นต้องมีคำอธิบายประกอบเพื่อให้ผู้ใช้ภายนอกสามารถทราบได้อย่างง่ายดายว่าบริการของคุณทำอะไรได้บ้างผ่านอินเทอร์เฟซ HTTP นั่นคือในระดับพื้นฐาน คำอธิบายประกอบจะต้องมีรายการทรัพยากรที่มีอยู่ วิธีการ HTTP เนื้อความของคำขอ รายการพารามิเตอร์ การบ่งชี้ส่วนหัวที่จำเป็นและได้รับการสนับสนุน ตลอดจนโค้ดส่งคืนและรูปแบบการตอบกลับ องค์ประกอบที่สำคัญอย่างยิ่งของคำอธิบายประกอบสัญญาคือคำอธิบายด้วยวาจา ("จะเกิดอะไรขึ้นหากคุณเพิ่มพารามิเตอร์การสืบค้นนี้ในคำขอ", "โค้ด 400 จะถูกส่งคืนในกรณีใด")

อย่างไรก็ตาม เมื่อพูดถึงการพัฒนาไมโครเซอร์วิสจำนวนมาก คุณต้องการแยกคุณค่าเพิ่มเติมจากคำอธิบายประกอบที่เป็นลายลักษณ์อักษร ตัวอย่างเช่น คุณสามารถสร้างทั้งโค้ดไคลเอ็นต์และเซิร์ฟเวอร์ในภาษาการเขียนโปรแกรมจำนวนมากโดยใช้ RAML/Swagger คุณยังสามารถรับเอกสารประกอบสำหรับไมโครเซอร์วิสได้โดยอัตโนมัติและอัปโหลดไปยังพอร์ทัลนักพัฒนาของคุณ :)

ตัวอย่างคำอธิบายสัญญาที่มีโครงสร้าง

พบได้น้อยคือการทดสอบไมโครเซอร์วิสตามคำอธิบายสัญญา หากคุณเขียนทั้งคำอธิบายประกอบและส่วนประกอบ คุณสามารถสร้างการทดสอบอัตโนมัติที่จะตรวจสอบความเพียงพอของบริการด้วยข้อมูลอินพุตประเภทต่างๆ บริการส่งคืนรหัสตอบกลับที่ไม่ได้อธิบายไว้ในคำอธิบายประกอบหรือไม่ จะสามารถประมวลผลข้อมูลที่ไม่ถูกต้องอย่างเห็นได้ชัดได้อย่างถูกต้องหรือไม่?

ยิ่งไปกว่านั้น การใช้งานคุณภาพสูงไม่เพียงแต่ในสัญญาเท่านั้น แต่ยังรวมถึงเครื่องมือสำหรับการแสดงคำอธิบายประกอบด้วยภาพ ทำให้งานไมโครเซอร์วิสง่ายขึ้น นั่นคือหากสถาปนิกอธิบายสัญญาในเชิงคุณภาพ นักออกแบบและนักพัฒนาจะใช้บริการในผลิตภัณฑ์อื่น ๆ โดยไม่มีค่าใช้จ่ายเวลาเพิ่มเติม

หากต้องการเปิดใช้งานเครื่องมือเพิ่มเติม ทั้ง RAML และ OAS สามารถเพิ่มข้อมูลเมตาที่ไม่ได้ระบุไว้ในมาตรฐาน (ตัวอย่างเช่น นี่คือวิธีการดำเนินการใน OAS).

โดยทั่วไป ขอบเขตของความคิดสร้างสรรค์ในการใช้สัญญาสำหรับไมโครเซอร์วิสนั้นมีมาก... อย่างน้อยก็ในทางทฤษฎี

เปรียบเทียบเม่นกับงู

ปัจจุบันพื้นที่การพัฒนาลำดับความสำคัญของ Acronis คือการพัฒนา Acronis Cyber ​​​​Platform Acronis Cyber ​​​​Platform คือจุดใหม่ของการบูรณาการบริการของบุคคลที่สามกับ Acronis Cyber ​​​​Cloud และส่วนของเอเจนต์ แม้ว่าเราจะพอใจกับ API ภายในของเราที่อธิบายไว้ใน RAML แต่ความจำเป็นในการเผยแพร่ API อีกครั้งทำให้เกิดคำถามในการเลือก: มาตรฐานคำอธิบายประกอบใดที่เหมาะกับงานของเราที่สุด

ในตอนแรก ดูเหมือนว่ามีสองวิธี - การพัฒนาที่พบบ่อยที่สุดคือ RAML และ Swagger (หรือ OAS) แต่ในความเป็นจริงปรากฎว่าไม่มีทางเลือกอย่างน้อย 2 ทาง แต่มี 3 ทางเลือกขึ้นไป

ในด้านหนึ่งมี RAML ซึ่งเป็นภาษาที่ทรงพลังและมีประสิทธิภาพ ใช้ลำดับชั้นและการสืบทอดอย่างดี ดังนั้นรูปแบบนี้จึงเหมาะสำหรับบริษัทขนาดใหญ่ที่ต้องการคำอธิบายจำนวนมาก ซึ่งไม่ใช่ผลิตภัณฑ์เดียว แต่เป็นไมโครเซอร์วิสจำนวนมากที่มีส่วนร่วมกันของสัญญา - รูปแบบการตรวจสอบสิทธิ์ ประเภทข้อมูลเดียวกัน ส่วนเนื้อหาข้อผิดพลาด .

แต่ Mulesoft ผู้พัฒนา RAML ได้เข้าร่วม Open API consortium ซึ่งกำลังพัฒนาอยู่ กรีดกราย. ดังนั้น RAML จึงระงับการพัฒนา หากต้องการจินตนาการถึงรูปแบบของกิจกรรม ลองจินตนาการว่าผู้ดูแลส่วนประกอบ Linux หลักถูกปล่อยให้ทำงานให้กับ Microsoft สถานการณ์นี้สร้างข้อกำหนดเบื้องต้นสำหรับการใช้ Swagger ซึ่งกำลังพัฒนาแบบไดนามิกและในเวอร์ชันที่สามล่าสุด - ใช้งานได้จริงตาม RAML ในแง่ของความยืดหยุ่นและฟังก์ชันการทำงาน

ถ้าไม่ใช่เพราะสิ่งหนึ่ง...

ปรากฎว่ายูทิลิตี้โอเพ่นซอร์สบางตัวไม่ได้รับการอัพเดตเป็น OAS 3.0 สำหรับไมโครเซอร์วิสใน Go สิ่งที่สำคัญที่สุดคือการขาดการปรับตัว ไปผยอง สำหรับเวอร์ชันมาตรฐานล่าสุด อย่างไรก็ตาม ความแตกต่างระหว่าง Swagger 2 และ Swagger 3 ก็คือ ใหญ่. ตัวอย่างเช่น ในเวอร์ชันที่สาม นักพัฒนา:

• ปรับปรุงคำอธิบายของแผนการรับรองความถูกต้อง
• ที่เสร็จเรียบร้อย รองรับสคีมา JSON
• อัพเกรดความสามารถในการเพิ่มตัวอย่าง

สถานการณ์เป็นเรื่องตลก: เมื่อเลือกมาตรฐานคุณต้องพิจารณา RAML, Swagger 2 และ Swagger 3 เป็นทางเลือกที่แยกจากกัน อย่างไรก็ตาม มีเพียง Swagger 2 เท่านั้นที่รองรับเครื่องมือ OpenSource ได้ดี RAML มีความยืดหยุ่นมาก...และซับซ้อน และ Swagger 3 ไม่ได้รับการสนับสนุนจากชุมชน ดังนั้น คุณจะต้องใช้เครื่องมือที่เป็นกรรมสิทธิ์หรือโซลูชันเชิงพาณิชย์ ซึ่งมักจะมีราคาค่อนข้างแพง

ยิ่งไปกว่านั้น หาก Swagger มีฟีเจอร์ดีๆ มากมาย เช่น พอร์ทัลสำเร็จรูป editor.swagger.ioซึ่งคุณสามารถอัปโหลดคำอธิบายประกอบและรับการแสดงภาพพร้อมคำอธิบายโดยละเอียด ลิงก์ และการเชื่อมต่อ จากนั้น RAML ที่เป็นพื้นฐานและเป็นมิตรน้อยกว่าจะไม่มีโอกาสดังกล่าว ใช่ คุณสามารถค้นหาบางอย่างจากโปรเจ็กต์บน GitHub ค้นหาอะนาล็อกที่นั่นและปรับใช้ด้วยตัวเอง อย่างไรก็ตาม ไม่ว่าในกรณีใด จะต้องมีคนดูแลพอร์ทัล ซึ่งไม่สะดวกสำหรับการใช้งานขั้นพื้นฐานหรือการทดสอบ นอกจากนี้การผยองนั้น "ไร้หลักการ" มากกว่าหรือมีเสรีนิยมมากกว่า - สามารถสร้างได้จากความคิดเห็นในโค้ดซึ่งแน่นอนว่าขัดแย้งกับหลักการแรกของ API และไม่ได้รับการสนับสนุนจากยูทิลิตี้ RAML ใด ๆ

ครั้งหนึ่งเราเริ่มทำงานกับ RAML ในฐานะภาษาที่ยืดหยุ่นมากขึ้น และด้วยเหตุนี้ เราจึงต้องทำอะไรหลายอย่างด้วยตัวเอง ตัวอย่างเช่น หนึ่งในโครงการใช้ยูทิลิตี้นี้ การแพร่กระจาย ในการทดสอบหน่วยซึ่งรองรับเฉพาะ RAML 0.8 ดังนั้นเราจึงต้องเพิ่มไม้ค้ำเพื่อให้ยูทิลิตี้สามารถ "กิน" RAML เวอร์ชัน 1.0 ได้

จำเป็นต้องเลือกมั้ย?

หลังจากทำงานเพื่อทำให้ระบบนิเวศของโซลูชันสำหรับ RAML เสร็จสมบูรณ์ เราได้ข้อสรุปว่าเราจำเป็นต้องแปลง RAML ให้เป็น Swagger 2 และดำเนินการอัตโนมัติ การตรวจสอบ การทดสอบ และการเพิ่มประสิทธิภาพที่ตามมาทั้งหมด นี่เป็นวิธีที่ดีในการใช้ประโยชน์จากทั้งความยืดหยุ่นของ RAML และการสนับสนุนเครื่องมือของชุมชนจาก Swagger

เพื่อแก้ไขปัญหานี้ มีเครื่องมือ OpenSource สองเครื่องมือที่ควรจัดให้มีการแปลงสัญญา:

1. oas-raml-แปลง เป็นยูทิลิตี้ที่ไม่รองรับในปัจจุบัน ในขณะที่ทำงานร่วมกับเราพบว่ามีปัญหาหลายประการกับ RAML ที่ซับซ้อนซึ่ง "กระจาย" ไปยังไฟล์จำนวนมาก โปรแกรมนี้เขียนด้วย JavaScript และดำเนินการสำรวจเส้นทางแบบเรียกซ้ำของแผนผังไวยากรณ์ เนื่องจากการพิมพ์แบบไดนามิก จึงกลายเป็นเรื่องยากที่จะเข้าใจโค้ดนี้ ดังนั้นเราจึงตัดสินใจที่จะไม่เสียเวลาในการเขียนแพตช์สำหรับยูทิลิตี้ที่กำลังจะตาย
2. webapi-parser - เครื่องมือจากบริษัทเดียวกันที่อ้างว่าพร้อมที่จะแปลงทุกสิ่งและในทุกทิศทาง จนถึงปัจจุบัน มีการประกาศการสนับสนุนสำหรับ RAML 0.8, RAML 1.0 และ Swagger 2.0 อย่างไรก็ตาม ในขณะที่ทำการวิจัย ยูทิลิตี้ยังคงอยู่ อย่างที่สุด ชื้นและใช้ไม่ได้ นักพัฒนาสร้างประเภทของ IRทำให้สามารถเพิ่มมาตรฐานใหม่ได้อย่างรวดเร็วในอนาคต แต่จนถึงตอนนี้มันก็ไม่ได้ผล

และนั่นไม่ใช่ปัญหาทั้งหมดที่เราพบ ขั้นตอนหนึ่งในไปป์ไลน์ของเราคือการตรวจสอบว่า RAML จากพื้นที่เก็บข้อมูลนั้นถูกต้องโดยสัมพันธ์กับข้อกำหนด เราลองใช้ยูทิลิตี้หลายอย่าง น่าแปลกที่พวกเขาสาบานต่อคำอธิบายประกอบของเราในที่ต่างๆ และใช้คำพูดที่ไม่ดีต่างกันโดยสิ้นเชิง และไม่ได้ตรงประเด็นเสมอไป :)

ในท้ายที่สุด เราก็ตัดสินใจในโครงการที่ล้าสมัยไปแล้ว ซึ่งก็มีปัญหาหลายประการเช่นกัน (บางครั้งก็ขัดข้องโดยไม่ทราบสาเหตุ มีปัญหาเมื่อทำงานกับนิพจน์ทั่วไป) ดังนั้นเราจึงไม่พบวิธีแก้ไขปัญหาการตรวจสอบและการแปลงโดยใช้เครื่องมือฟรี และตัดสินใจใช้ยูทิลิตี้เชิงพาณิชย์ ในอนาคต เมื่อเครื่องมือ OpenSource มีความสมบูรณ์มากขึ้น ปัญหานี้อาจแก้ไขได้ง่ายขึ้น ในระหว่างนี้ต้นทุนแรงงานและเวลาในการ "ตกแต่ง" สำหรับเราดูเหมือนมีความสำคัญมากกว่าต้นทุนการบริการเชิงพาณิชย์

ข้อสรุป

ท้ายที่สุด เราต้องการแบ่งปันประสบการณ์ของเราและทราบว่าก่อนที่จะเลือกเครื่องมือในการอธิบายสัญญา คุณต้องกำหนดอย่างชัดเจนว่าคุณต้องการอะไรจากสัญญา และงบประมาณที่คุณยินดีลงทุน หากเราลืมเกี่ยวกับ OpenSource ก็มีบริการและผลิตภัณฑ์จำนวนมากที่จะช่วยคุณตรวจสอบ แปลง และตรวจสอบความถูกต้อง แต่มีราคาแพงและบางครั้งก็แพงมาก สำหรับบริษัทขนาดใหญ่ ต้นทุนดังกล่าวก็พอทนได้ แต่สำหรับสตาร์ทอัพ อาจกลายเป็นภาระใหญ่ได้

กำหนดชุดเครื่องมือที่คุณจะใช้ในภายหลัง ตัวอย่างเช่น หากคุณต้องการแสดงสัญญา การใช้ Swagger 2 ซึ่งมี API ที่สวยงามจะง่ายกว่า เนื่องจากใน RAML คุณจะต้องสร้างและบำรุงรักษาบริการด้วยตัวเอง
ยิ่งคุณมีงานมากเท่าใด ความต้องการเครื่องมือก็จะยิ่งกว้างขึ้นเท่านั้น และเครื่องมือก็จะแตกต่างกันไปตามแพลตฟอร์มต่างๆ และจะเป็นการดีกว่าหากคุณทำความคุ้นเคยกับเวอร์ชันที่มีอยู่ทันที เพื่อที่จะตัดสินใจเลือกที่จะช่วยลดต้นทุนของคุณในอนาคตให้เหลือน้อยที่สุด

แต่ก็คุ้มค่าที่จะตระหนักว่าระบบนิเวศทั้งหมดที่มีอยู่ในปัจจุบันนั้นไม่สมบูรณ์ ดังนั้นหากมีแฟน ๆ ในบริษัทที่ชอบทำงานใน RAML เพราะ “มันช่วยให้คุณแสดงความคิดได้อย่างยืดหยุ่นมากขึ้น” หรือในทางกลับกัน ชอบ Swagger เพราะ “ชัดเจนกว่า” ทางที่ดีควรปล่อยให้พวกเขาทำงาน ในสิ่งที่เป็นอยู่ พวกเขาคุ้นเคยกับมันและต้องการมัน เพราะเครื่องมือในรูปแบบใดๆ จำเป็นต้องมีการแก้ไขด้วยไฟล์

สำหรับประสบการณ์ของเรา ในโพสต์ต่อไปนี้ เราจะพูดถึงการตรวจสอบแบบคงที่และไดนามิกที่เราดำเนินการตามสถาปัตยกรรม RAML-Swagger ของเรา รวมถึงเอกสารที่เราสร้างจากสัญญา และวิธีการทำงานทั้งหมด

เฉพาะผู้ใช้ที่ลงทะเบียนเท่านั้นที่สามารถเข้าร่วมในการสำรวจได้ เข้าสู่ระบบ, โปรด.

คุณใช้ภาษาใดในการอธิบายสัญญาไมโครเซอร์วิส

• RAML 0.8

• RAML 1.0

• สแวกเกอร์ 2

• OAS3 (อาคา)

• พิมพ์เขียว

• อื่น ๆ

• ไม่ได้ใช้

ผู้ใช้ 100 คนโหวต ผู้ใช้ 24 รายงดออกเสียง

ที่มา: will.com