ความสมบูรณ์ของเอกสารประกอบของ API กำหนดว่ามีประโยชน์อย่างไร ใช้ขั้นตอนมาตรฐานเมื่อเขียนเอกสารประกอบของ REST API เพื่อสร้างคู่มือที่อ่านและทำความเข้าใจได้ง่ายกว่าสำหรับผู้อ่านทุกคน คู่มืออ้างอิงฉบับย่อที่ครอบคลุมทุกอย่างที่คุณต้องการเพื่อเรียนรู้เกี่ยวกับ API รวมถึงข้อมูลเกี่ยวกับขั้นตอน ประเภท ประเภทผลลัพธ์ พารามิเตอร์ และอื่นๆ เป็นไปได้ด้วยเอกสารประกอบของ REST API บทความนี้จะแนะนำคุณเกี่ยวกับ REST API วิธีเขียนเอกสาร REST API และเคล็ดลับและเครื่องมือสำหรับการเขียนเอกสารประกอบ
เกี่ยวกับ REST API
REST API ช่วยให้แอปพลิเคชันอินเทอร์เน็ตต่างๆ สื่อสารกันได้ง่ายขึ้น คุณสามารถรับข้อมูลจากโปรแกรมอื่นได้เมื่อใช้โปรแกรมนั้น คุณสามารถใช้ RESTful API แทนวิธีการทั่วไป ซึ่งใช้เวลานานกว่าและมีความปลอดภัยน้อยกว่า เมื่อใช้ API คุณสามารถรับข้อมูลจากระบบโดยไม่ต้องมีส่วนร่วมกับอินเทอร์เฟซผู้ใช้
REST เป็นแนวทางการออกแบบสถาปัตยกรรมและการเขียนโปรแกรมยอดนิยมสำหรับแพลตฟอร์มไฮเปอร์มีเดียบนเครือข่ายและเทคโนโลยีเว็บอื่นๆ ตัวอย่างเช่น Instagram API จะส่งคืนสถานะ ตัวตน การเชื่อมต่อ และทวีตที่แบ่งปันของผู้ใช้ เมื่อโปรแกรมเมอร์ขอวัตถุของลูกค้า ด้วยการรวม API สิ่งนี้เป็นไปได้
คุณเขียนเอกสาร API อย่างไร
เอกสารประกอบที่ดีกว่าควรทำหน้าที่เป็นทั้งคู่มือและเครื่องมือทางการศึกษา ช่วยให้นักพัฒนาสามารถค้นหารายละเอียดที่ต้องการได้อย่างรวดเร็วและเรียนรู้วิธีรวมเทคนิคที่พวกเขากำลังพิจารณาโดยการตรวจสอบเอกสารประกอบ ด้วยเหตุนี้ เอกสารประกอบที่เพียงพอจึงต้องมีความกระชับและมองเห็นได้ โดยนำเสนอสิ่งต่อไปนี้:
- คำอธิบายโดยละเอียดเกี่ยวกับสิ่งที่เทคนิคหรือรายการทำ
- การแจ้งที่แจ้งรายละเอียดที่สำคัญแก่นักพัฒนา เช่น ปัญหาและข้อควรระวัง
- ตัวอย่างการโทรพร้อมเนื้อหาของประเภทสื่อที่เกี่ยวข้อง
- รายการตรวจสอบของตัวแปรที่ใช้โดยเทคนิคนี้ พร้อมด้วยข้อมูลเกี่ยวกับชนิดของตัวแปร ข้อกำหนดด้านโครงสร้างเฉพาะ และถ้าจำเป็น
- ตัวอย่างการตอบกลับด้วยเนื้อหาประเภทสื่อ
- ตัวอย่างสคริปต์ในหลายภาษาที่มีโค้ดที่จำเป็นทั้งหมด (เช่น Java, .Net, Ruby เป็นต้น)
- อินสแตนซ์ SDK
- พวกเขาสาธิตวิธีใช้ SDK สำหรับภาษาของตนเพื่อเข้าถึงบริการหรือขั้นตอน
- กิจกรรมที่มีคุณค่าในการทดสอบและลองใช้คำขอ API (คอนโซล API, โน้ตบุ๊ก API)
- คำถามและสถานการณ์เกี่ยวกับรหัสมักถูกตั้งคำถาม
- การอ้างอิงถึงเว็บไซต์ที่เกี่ยวข้อง (ตัวอย่าง บล็อก ฯลฯ)
เคล็ดลับที่ดีที่สุดในการเขียนเอกสาร RESTful API
วางแผนกลยุทธ์ของคุณสำหรับการเขียนเอกสาร
เมื่อเริ่มกระบวนการจัดทำเอกสาร คุณต้องสร้างกลยุทธ์อย่างละเอียด ความน่าจะเป็นของความสำเร็จของคุณจะเพิ่มขึ้น ทำความเข้าใจผู้อ่านที่คุณสร้างเอกสารคู่มือก่อนที่คุณจะจัดทำเอกสาร REST API คุณสามารถเลือกแพลตฟอร์ม สไตล์ และเค้าโครงที่เหมาะสมสำหรับเอกสารของคุณได้อย่างง่ายดาย หากคุณทราบกลุ่มเป้าหมายของคุณ
คุณจะสร้างเนื้อหาที่เกี่ยวข้องได้ง่ายขึ้นซึ่งจะปรับปรุงการใช้งาน API ของคุณหากคุณเข้าใจเป้าหมายและขอบเขตของการจัดทำเอกสาร REST API อย่างชัดเจน คุณอาจจัดระเบียบเอกสารเพื่อให้ตรงกับความต้องการของผู้ใช้มากขึ้นโดยการเขียน REST API ร่วมกับพวกเขาในการพิจารณา
โปรดจำไว้ว่าผู้บริโภคมีความรู้สึกนึกคิดเกี่ยวกับสถานการณ์ปฏิบัติการของคุณ เมื่อพวกเขาใช้ API ของคุณ ตัวอย่างเช่น ผู้ใช้มักจะพิจารณาถึงค่าใช้จ่ายเอกสาร API การส่งคืน ลูกค้า และบัตรเดบิต หากคุณเสนอวิธีการชำระเงิน
ดังนั้น การจัดระเบียบเอกสารของคุณในลักษณะนั้นทำให้มีเหตุผล ลองศึกษาเอกสารประกอบสำหรับ Stripe API พวกเขาให้คำแนะนำที่ดีก่อนที่จะจัดกลุ่ม API อย่างมีเหตุผล GitHub นำเสนอภาพประกอบที่สมบูรณ์ของเอกสารประกอบ RESTful API ที่มีการจัดระเบียบอย่างดี โดยมีส่วนสำหรับ "ข้อมูล ปัญหา และสมาชิกของ GitHub"
GitHub ช่วยให้คุณสร้างคำขอดึง แบรนช์ และอื่นๆ เอกสาร GitHub API เป็นโอเพ่นซอร์ส ส่วนที่ดีที่สุดเกี่ยวกับ GitHub คือมีความมุ่งมั่นที่จะปรับปรุงประสบการณ์ของนักพัฒนาในรูปแบบที่สำคัญอยู่เสมอ
รวมส่วนพื้นฐาน
เอกสาร RESTful API ที่ยอดเยี่ยมต้องมีชิ้นส่วนจำนวนหนึ่ง ส่วนหลักดังกล่าวมีความสำคัญในการเพิ่มความชัดเจนและเพิ่มการยอมรับ REST API เมื่อจัดทำเป็นเอกสาร คุณควรพิจารณาองค์ประกอบที่สำคัญบางประการในขณะที่จัดทำเอกสาร REST API
- ข้อมูลเบื้องต้นเกี่ยวกับ REST API
- วิธีรับข้อมูลรับรองผู้ใช้
- ทรัพยากรที่จำเป็นสำหรับการใช้ API
- ข้อความแสดงข้อผิดพลาดเมื่อสื่อสารกับ API
- ข้อกำหนดการใช้งาน
รักษาความซื่อสัตย์และหลีกเลี่ยงศัพท์แสง
การใช้คำศัพท์ที่สอดคล้องกันตลอดทั้งข้อความเป็นอีกวิธีที่มีประโยชน์สำหรับการจัดทำเอกสาร RESTful API ใช้รูปแบบการเขียนที่สอดคล้องกันโดยไม่มีความไม่สอดคล้องกันทางภาษาและการเข้ารหัส ลบส่วนที่ไม่ชัดเจนหรือท้าทายในการทำความเข้าใจออกหลังจากตรวจทานเนื้อหาของคุณอย่างละเอียด
ใช้คำศัพท์และมาตรฐานคำศัพท์ที่สอดคล้องกันเสมอ ใช้จินตนาการของคุณเมื่อใช้โปรโตคอล HTTP รหัสสถานะ และชื่อรายการทั่วไปอื่นๆ ที่อาจนำไปสู่ความเข้าใจผิด ตัวอย่างเช่น เมื่ออธิบาย REST API ควรใช้คำกริยา GET HTTP เพื่อสืบค้นข้อมูลจากทรัพยากรที่ระบุ คุณไม่จำเป็นต้องเขียนเหตุผลมากมายหากคุณยึดบรรทัดฐานที่ทราบ และเอกสารของคุณจะอ่านง่ายขึ้น จะช่วยได้หากคุณละเว้นจากการใช้ภาษาทางเทคนิคมากเกินไปในคำอธิบาย API ของคุณ ตรวจสอบให้แน่ใจว่าคุณใช้ภาษาที่ตรงไปตรงมาซึ่งตรงกับความต้องการของผู้ชมหลักของคุณ
เพิ่มภาพประกอบเชิงโต้ตอบ
นักพัฒนาส่วนใหญ่ชอบทดสอบสิ่งที่พวกเขาได้อ่านในเอกสารเพื่อดูว่ามีประสิทธิภาพหรือไม่ ในภาษาการเขียนโปรแกรมที่นักพัฒนาส่วนใหญ่คุ้นเคย ให้รวมโปรแกรมตัวอย่างแบบไดนามิก สิ่งนี้จะทำให้การพัฒนา API มีความซับซ้อนน้อยลง
การรวม ตัวอย่าง REST API แบบไดนามิกเป็นเทคนิคที่มีประสิทธิภาพในการลดช่วงการเรียนรู้ในขณะที่ใช้ API ของคุณ นอกจากนี้ คุณอาจรวมข้อมูลการทดสอบที่ผู้ใช้สามารถใช้เพื่อส่งคำแนะนำและตรวจสอบประเภทการตอบกลับที่ได้รับ
เมื่อจัดทำเอกสาร REST API คุณสามารถรวมเนื้อหาอื่นนอกเหนือจากตัวอย่างจริงได้ สิ่งนี้จะช่วยผู้ใช้ในการใช้ประโยชน์สูงสุดจาก API นอกเหนือจากข้อมูลที่มีให้ในคำแนะนำ คู่มือการตั้งค่าบัญชี เฟรมเวิร์ก เครื่องมือการพัฒนา และการสัมมนาเป็นเอกสารบางส่วนที่อาจใช้เพื่อเสริมคำอธิบาย API
เขียนสำหรับตำแหน่งระดับเริ่มต้น
นักเขียนมืออาชีพ ไม่ใช่นักพัฒนา มักจะสร้างเอกสารประกอบ เนื่องจากผู้เขียนด้านเทคนิคเชี่ยวชาญในการตีความแนวคิดทางเทคนิคเป็นภาษาที่เข้าใจได้ อย่างไรก็ตาม นักเขียนด้านเทคนิคหลายคนใช้คำศัพท์ทางเทคนิคในคู่มือของตน API แต่ละรายการได้รับการพัฒนาโดยคำนึงถึงผู้ชมที่เฉพาะเจาะจง
เอกสาร API มีผู้ชมจำนวนมาก รวมถึงนักพัฒนา ทีมตัดสิน และผู้สังเกตการณ์ นักพัฒนามีส่วนร่วมกับเอกสารประกอบ ทีมตัดสิน เช่น วิศวกรและ CTO จะเข้าใจได้อย่างรวดเร็วว่า API นั้นเหมาะสมหรือไม่ และผู้ชม เช่น นักเขียนเทคโนโลยี นักข่าว และคู่แข่งของคุณ
บุคคลเหล่านี้มีหน้าที่และความสามารถที่แตกต่างกัน และควรผ่อนคลายในขณะที่ดูเอกสาร REST API ของคุณ ดังนั้นคุณควรให้ความสำคัญกับผู้บริโภคที่ไม่มีประสบการณ์มากที่สุด ใช้เทคนิคข้างต้นเมื่อจัดทำเอกสาร REST API เพื่อรับประกันว่าเอกสาร REST API นั้นเข้าใจได้โดยบุคคลที่มีความรู้ API ในระดับต่างๆ
เครื่องมือที่ดีที่สุดสำหรับการสร้างเอกสาร RESTful API
วิธีการที่เอกสารทางเทคนิคได้รับการปรับปรุงโดยใช้เครื่องมือสำหรับ Restful API นักเขียนด้านเทคนิคสามารถใช้ เครื่องมือเอกสารประกอบ REST API เหล่านี้เพื่อสร้างเอกสารเผยแพร่ทางเทคนิค หากพวกเขาคุ้นเคยกับการเขียนโค้ด เนื่องจากมีการใช้งานผู้สร้างเอกสาร API อย่างกว้างขวาง ผู้ผลิตที่มีชื่อเสียงที่สุดจึงใช้งานได้ฟรีและรองรับ OpenAPI v3 ด้านล่าง ผู้เขียนด้านเทคนิคใช้ทรัพยากรเหล่านี้เพื่อจัดทำเอกสาร REST API
SwaggerHub
SwaggerHub เป็นแพลตฟอร์มเอกสาร API ดิจิทัลที่สร้างขึ้นเพื่อปรับปรุงประสิทธิภาพและเร่งรัดเอกสาร Rest API ทำให้สมบูรณ์แบบสำหรับทีมและธุรกิจ คุณสามารถปฏิบัติตามข้อกำหนดของ OpenAPI ( OAS) ซึ่งก่อนหน้านี้เรียกว่า Swagger ได้รวดเร็วยิ่งขึ้น โดยใช้ตัวแก้ไข API
คุณสมบัติบางอย่างคือ:
- การรายงานข้อผิดพลาดที่มีประสิทธิภาพและการเติมภาษาอัตโนมัติ
- แนวทางการออกแบบ API แบบรวมที่บังคับใช้มาตรฐานอย่างต่อเนื่อง
- เว็บไซต์สำหรับจัดเก็บและใช้งานไวยากรณ์ OAS ที่เป็นสากลใน API
- การติดตามปัญหาตามเวลาจริงและความคิดเห็น
- มอบประสบการณ์นักพัฒนาที่ยอดเยี่ยม
Redocly
กระบวนการสำหรับเอกสาร REST API เป็นไปโดยอัตโนมัติโดยใช้โซลูชันเวิร์กโฟลว์ของ Redocly คุณสามารถจัดการเอกสารของคุณ เช่น โค้ดโปรแกรมโดยใช้เอกสารเสมือนจริงโดยบันทึกไว้ในซอฟต์แวร์รุ่นพิเศษ กำหนดขั้นตอนการตรวจสอบ และส่งไปยังการตั้งค่าต่างๆ สิทธิ์ของผู้ใช้ การพยายามตรวจสอบความถูกต้อง และกลไกการพิสูจน์ตัวตนอื่นๆ ของ Redocly ช่วยให้คุณรับประกันเพิ่มเติมได้ว่าทีมของคุณทำงานร่วมกันอย่างมีประสิทธิภาพและปลอดภัย ความสามารถในการแสดงผลของ Redocly เป็นอีกหนึ่งคุณลักษณะเฉพาะ เพื่อให้แน่ใจว่าการปรับเปลี่ยนของคุณได้รับการประเมินและถกเถียงก่อนที่จะส่งไปยังสาธารณะ คุณสามารถดูตัวอย่างแต่ละโครงการและคำขอแพตช์
Stoplight
เมื่อใช้ยูทิลิตีการเขียน REST API ของ Stoplight คุณสามารถสร้างและให้บริการเอกสาร API แบบดิจิทัลได้ การใช้ซอฟต์แวร์นี้ คุณสามารถสร้างเอกสารประกอบ REST API แบบไดนามิกที่คุณสามารถแจกจ่ายภายในและภายนอกให้กับบุคคลทั่วไปได้ คุณอาจรวมบทความเชิงปฏิบัติ คู่มือการใช้งาน และตัวอย่างโค้ดที่สร้างขึ้นในภาษาการเขียนโปรแกรมต่างๆ เช่น JavaScript , Python และ Java
คุณสามารถโพสต์เอกสารของคุณบน Stoplight ซึ่งเป็นหนึ่งในคุณสมบัติที่สำคัญของโซลูชันเอกสาร REST API ของเรา สิ่งนี้ทำให้คุณไม่ต้องกังวลเกี่ยวกับเซิร์ฟเวอร์ปฏิบัติการ และทำให้ง่ายต่อการใช้ตัวเชื่อมต่อเพื่อจัดการสิทธิ์และติดตามเมตริก
ReadMe
เอกสาร API ของคุณสามารถกลายเป็นศูนย์กลางไดนามิกสำหรับนักพัฒนาของคุณด้วย ReadMe พวกเขาสามารถสร้างตัวอย่างโค้ดโดยอัตโนมัติ แก้ไขเนื้อหาในโปรแกรมแก้ไข ReadMe รวมการแก้ไขที่แนะนำ ตอบคำถามในกระดานสนทนา และอื่นๆ อีกมากมายในฮับนี้
ข้อดีอย่างหนึ่งที่สำคัญที่สุดของ ReadMe คือการวิเคราะห์ เช่น การเข้าชมหน้าเว็บ คำขอ API ความล้มเหลวของ API และการสืบค้นไปยังเว็บไซต์ต่างๆ เป็นต้น ดังนั้นคุณจึงสามารถดูได้ว่าอินเทอร์เฟซการเขียนโปรแกรมแอปพลิเคชันและเอกสารประกอบ REST API ของคุณถูกนำไปใช้อย่างไร การใช้เมตริกเหล่านี้ ทีมงานของคุณอาจกำหนดได้ว่าจะมุ่งความสนใจไปที่ใดเพื่อปรับปรุง
apiDoc
โซลูชันเอกสาร REST API แบบโอเพ่นซอร์สที่เรียกว่า apiDoc สร้างเอกสารประกอบจากโค้ดเบสที่มีรายละเอียด API ด้วยภาษาการเขียนโปรแกรมทุกภาษาจึงเข้ากันได้ วิศวกรสามารถสังเกตสิ่งที่ถูกแก้ไขระหว่างรุ่นต่างๆ ของ API ได้ เนื่องจาก apiDoc ช่วยให้คุณทำเช่นนั้นได้ สิ่งนี้อำนวยความสะดวกในการจัดการการอัปเดต API อย่างสมบูรณ์ ซึ่งมักเรียกว่าการกำหนดเวอร์ชัน API
DapperDox
DapperDox ได้รับการพัฒนาโดยผู้เขียนเอกสาร RESTful API สำหรับผู้เขียนเอกสาร REST API เพื่อให้นักเขียนมีอิสระที่พวกเขาต้องการและนักพัฒนาสามารถอ่านได้ง่ายตามที่พวกเขาต้องการ โซลูชันเอกสาร Web API นี้เหมาะอย่างยิ่งสำหรับการสร้างคอลเล็กชันเอกสารประกอบที่สอดคล้องกันซึ่งมีคำแนะนำที่เข้าใจได้และมาตรฐาน Web API เนื่องจากช่วยให้ผู้เขียนเพิ่มเนื้อหาที่เกี่ยวข้องลงในไซต์คำอธิบายที่สร้างขึ้นได้ นอกจากนี้ คุณสามารถอ้างอิงโยงได้ตามความจำเป็น อธิบายข้อกำหนด API ต่างๆ เป็นกลุ่มของสินค้า และเลือกธีมเพื่อจัดรูปแบบเอกสารของคุณให้แตกต่างออกไป
DocGen โดย LucyBot
คุณสามารถสร้างและจัดการเอกสารไดนามิก API โดยใช้ LucyBot ของ DocGen โปรแกรมนี้สร้างเอกสารประกอบสำหรับทุกเมธอดและอาร์กิวเมนต์ของ API และตอบกลับทันที คุณสามารถสร้างคอนโซล API เพื่อให้ผู้สร้างและผู้ใช้สามารถดำเนินการตามคำขอทดลองใช้ API เพื่อตรวจสอบ แก้ไขปัญหา และทำความเข้าใจกับ API ของคุณได้มากขึ้น คุณยังสามารถสร้างกระบวนการที่แสดงให้ผู้ใช้เห็นว่าต้องสร้างโค้ดใดและขั้นตอนที่ต้องปฏิบัติตามเพื่อให้งานใดงานหนึ่งเสร็จสมบูรณ์ในภาษาซอฟต์แวร์ที่พวกเขาเลือก
AppMaster
AppMaster แตกต่างจากแพลตฟอร์มอื่นตรงที่นักพัฒนาไม่จำเป็นต้องสร้างเอกสารประกอบ REST API และอัปเดตด้วยตนเอง แพลตฟอร์มนี้สร้างและอัปเดตเอกสาร REST API โดยอัตโนมัติในรูปแบบ Swagger ( OpenAPI) สำหรับแต่ละแอปพลิเคชัน และยังรวม Swagger UI ในแต่ละแอปพลิเคชันเซิร์ฟเวอร์เพื่อให้นักพัฒนาบุคคลที่สามสามารถรวมเข้ากับแอปพลิเคชันที่สร้างขึ้นได้ง่ายขึ้น นอกจากนี้ แพลตฟอร์ม AppMaster เมื่อสร้างเอกสารประกอบ REST API จะมีคำอธิบายของ จุดสิ้นสุด และกระบวนการทางธุรกิจที่เกี่ยวข้องโดยอัตโนมัติในคำอธิบายของแต่ละจุดสิ้นสุด ทำให้นักพัฒนาไม่ต้องสร้างหรืออัปเดตเอกสารประกอบอีกต่อไป
คำสุดท้าย
เครื่องมือเอกสาร API ทั้งหมดที่กล่าวถึงในบทความนี้สามารถสร้างเอกสาร API ที่มีคุณภาพได้ เป็นไปไม่ได้ที่จะประกาศว่าเครื่องดนตรีชิ้นใดชิ้นหนึ่งเป็นเครื่องดนตรีที่ยิ่งใหญ่ที่สุด ประสบการณ์และเกณฑ์ทั้งหมดของซอฟต์แวร์จัดทำเอกสาร API จะถูกกำหนดโดยมาตรฐาน แนวคิด เป้าหมาย และข้อกำหนดด้านเอกสารของลูกค้า
