ฉันจะเขียนเอกสาร API ที่ชัดเจนซึ่งนักพัฒนาของคุณสามารถปฏิบัติตามได้ตั้งแต่วันแรก

เหตุใดเอกสาร API ส่วนใหญ่จึงล้มเหลว

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

ฉันเขียนมันอย่างไร

จากแหล่งที่มา ไม่ใช่จากความทรงจำ ฉันอ่านเส้นทาง, เลเยอร์การตรวจสอบความถูกต้อง และตัวจัดการข้อผิดพลาด จากนั้นเรียกใช้ API ด้วยข้อมูลประจำตัวจริง ตัวอย่างทุกรายการในเอกสารคือคำขอที่ฉันทำและการตอบกลับที่ฉันได้รับ — ไม่มีเพย์โหลดที่สร้างขึ้นเอง, ไม่มีรหัสสถานะที่จุดสิ้นสุดไม่เคยส่งคืน

เอกสารประกอบด้วยอะไรบ้าง

• การตรวจสอบสิทธิ์: การรับโทเค็น, การรีเฟรช และสิ่งที่เกิดขึ้นเมื่อหมดอายุระหว่างเซสชัน
• ทุกจุดสิ้นสุดพร้อมพารามิเตอร์, ตัวอย่างคำขอที่สมบูรณ์ และรูปแบบการตอบกลับจริง
• การอ้างอิงข้อผิดพลาดที่แมปโค้ดข้อผิดพลาดแต่ละรายการกับสาเหตุและการแก้ไข แทนที่จะเพียงแค่ทำซ้ำข้อความ
• เส้นทางเริ่มต้นใช้งานที่นำนักพัฒนาใหม่จากศูนย์ไปสู่การเรียกใช้ที่สำเร็จในเวลาไม่ถึงสิบนาที
• อัตราการจำกัด, การแบ่งหน้า, webhooks และ idempotency อธิบายในที่ที่เกี่ยวข้องจริง

รูปแบบ

Markdown ในที่เก็บของคุณ, จัดโครงสร้างสำหรับ OpenAPI หรือไซต์เอกสาร — แล้วแต่ว่าคุณจะบำรุงรักษาจริง ตัวอย่างโค้ดในภาษาที่ผู้ใช้ของคุณสอบถาม, ตรวจสอบโดยการรัน Postman หรือคอลเลกชันที่คล้ายกันรวมอยู่ด้วยหากคุณต้องการ

สิ่งที่ฉันต้องการ

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

ไม่รวม

สำเนาทางการตลาด สิ่งนี้จะบันทึกสิ่งที่ซอฟต์แวร์ทำอย่างแม่นยำ หน้า Landing Page เป็นงานฝีมือที่แตกต่างกัน

ระยะเวลาและการสื่อสาร

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