วิธีสร้างและโฮสต์ API Docs จาก Bruno

ถ้าคุณเคยนำ Bruno มาใช้ คุณก็จะรู้ถึงข้อดีของมันอยู่แล้ว ชุดรวมของคุณจะอยู่ในรูปของไฟล์ .bru ธรรมดาใน Git repo ของคุณ ซึ่งมีการควบคุมเวอร์ชันควบคู่ไปกับโค้ด โดยไม่จำเป็นต้องมีบัญชีคลาวด์ เป็นคำตอบที่ชัดเจนและเน้นการทำงานแบบออฟไลน์เป็นอันดับแรกสำหรับไคลเอนต์ API ที่ต้องการเป็นเจ้าของข้อมูลของคุณ

แต่ไม่ช้าก็เร็วจะมีคนถามคำถามที่ Bruno ตอบได้ไม่ดีนัก: “เอกสารอยู่ที่ไหน? ส่งลิงก์มาให้หน่อยได้ไหม?” นี่คือจุดที่ทีมติดขัด Bruno สร้างขึ้นมาเพื่อส่งคำขอ ไม่ใช่เพื่อเผยแพร่พอร์ทัลเอกสารที่สามารถแชร์ได้ คู่มือนี้จะครอบคลุมการสร้างเอกสาร API ของ Bruno อย่างตรงไปตรงมา สิ่งที่ Bruno ให้คุณ สิ่งที่มันไม่ได้ให้ และวิธีสร้างและโฮสต์เอกสารจากข้อกำหนดของคุณเมื่อคุณต้องการ URL จริงเพื่อมอบให้กับผู้ใช้งาน

สิ่งที่ทีมต้องการจริงๆ จากเอกสาร API

ก่อนที่จะตัดสินเครื่องมือใดๆ การกำหนดเป้าหมายก็เป็นสิ่งสำคัญ เมื่อคนพูดถึง "เอกสาร API" พวกเขามักจะหมายถึงสามสิ่งนี้ที่ทำงานร่วมกัน:

• URL ที่สามารถแชร์ได้ นักพัฒนาส่วนหน้า, พาร์ทเนอร์ และ QA จำเป็นต้องอ่านเอกสารโดยไม่ต้องโคลน repo หรือติดตั้งไคลเอนต์ แค่ส่งลิงก์ใน Slack ก็ใช้งานได้ทันที
• เอกสารที่ซิงค์กันอยู่เสมอ เอกสารที่คลาดเคลื่อนจาก API จริงนั้นแย่กว่าไม่มี เพราะมันทำให้คนเข้าใจผิดอย่างมั่นใจ เอกสารต้องติดตามข้อกำหนด
• ประสบการณ์ "ลองใช้" แบบโต้ตอบ การอ่านคำอธิบาย endpoint นั้นดีอยู่แล้ว แต่การส่งคำขอจริงกับ endpoint ที่มีเอกสารครบถ้วน พร้อมการรับรองความถูกต้องและตัวอย่าง payload ที่กรอกไว้ เป็นสิ่งที่เปลี่ยนเอกสารให้เป็นข้อมูลอ้างอิงที่ใช้งานได้จริง

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

เรื่องราวของเอกสาร Bruno

มาทำความเข้าใจ Bruno อย่างยุติธรรม เพราะมันก็มีข้อดีบางอย่างในเรื่องนี้

ชุดรวมของ Bruno สามารถอ่านได้ง่ายสำหรับมนุษย์ รูปแบบ .bru เป็นข้อความธรรมดา ดังนั้นวิศวกรที่กำลังดู repo สามารถเปิดไฟล์คำขอและดูเมธอด, URL, ส่วนหัว และเนื้อหาได้ Bruno ยังรองรับบล็อก docs สำหรับแต่ละคำขอและมุมมองเอกสาร Markdown ภายในแอปพลิเคชัน ดังนั้นคุณสามารถแนบข้อความอธิบายว่า endpoint ทำอะไรได้บ้าง เนื่องจากทุกอย่างอยู่ใน Git บันทึกเหล่านั้นจึงได้รับการตรวจสอบในการขอรวม (pull requests) เช่นเดียวกับการเปลี่ยนแปลงอื่นๆ สำหรับทีมภายในที่ทำงานในโค้ดเบส นี่ถือเป็นรูปแบบเอกสารที่ถูกต้องตามกฎหมาย

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

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

หลักการ "Docs-as-Code"

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

ในเวิร์กโฟลว์ docs-as-code API ของคุณจะถูกอธิบายเพียงครั้งเดียวในข้อกำหนดที่เครื่องอ่านได้ โดยทั่วไปคือ OpenAPI ข้อกำหนดนั้นจะอยู่ใน Git, ได้รับการตรวจสอบในการขอรวม (pull requests) และทำหน้าที่เป็นสัญญา เอกสาร, เซิร์ฟเวอร์จำลอง และ SDK ไคลเอนต์ ล้วนถูกสร้างขึ้น*จาก*ข้อกำหนดนั้น เมื่อมีการเปลี่ยนแปลงสัญญา การเปลี่ยนแปลงจะถูกตรวจสอบในที่เดียว และทุกอย่างที่ตามมาก็จะเปลี่ยนแปลงตามไปด้วย

ข้อดีคือไม่มีงาน "อัปเดตเอกสาร" แยกต่างหากให้ลืม เอกสารเป็นเพียงการแสดงผลของข้อกำหนด หากข้อกำหนดถูกต้องและได้รับการตรวจสอบ เอกสารก็จะถูกต้อง นี่คือหลักการที่ Bruno สื่อถึงโดยการเก็บคอลเล็กชันไว้ใน Git แต่ก็ยังขาดขั้นตอนการเผยแพร่ไป

สร้างและโฮสต์เอกสารจากข้อกำหนดของคุณแทน

นี่คือช่องว่างที่ Apidog ถูกสร้างขึ้นมาเพื่อเติมเต็ม Apidog รักษาโมเดลความคิดที่เน้นข้อกำหนดและเป็นมิตรกับ Git แบบเดียวกัน จากนั้นเพิ่มส่วนที่ Bruno ละเลยไป: มันสร้างเว็บไซต์เอกสารแบบโต้ตอบที่โฮสต์โดยตรงจากข้อกำหนดของคุณ โดยไม่จำเป็นต้องมีไปป์ไลน์การสร้างแยกต่างหาก

ชี้ Apidog ไปที่ข้อกำหนด OpenAPI ของคุณ แล้วมันจะสร้างพอร์ทัลเอกสารโดยอัตโนมัติ ผลลัพธ์ที่ได้คือ:

• โฮสต์บน URL ที่สามารถแชร์ได้ ดังนั้นใครก็ตามที่มีลิงก์สามารถอ่านเอกสารได้โดยไม่ต้องติดตั้งอะไรเลย
• สามารถติดตั้งบนโดเมนที่กำหนดเองได้ ดังนั้นเอกสารสามารถอยู่ภายใต้ docs.yourcompany.com และเข้ากับแบรนด์ของคุณได้
• โต้ตอบได้ ด้วยแผง "ลองใช้" ในตัวที่ส่งคำขอจริงโดยใช้พารามิเตอร์, ส่วนหัว และการรับรองความถูกต้องที่มีเอกสารครบถ้วน
• สร้างขึ้นจากข้อกำหนด ดังนั้นเอกสารจะสะท้อนถึงสิ่งที่ API ประกาศจริง แทนที่จะเป็นสำเนาที่เขียนด้วยมือซึ่งอาจคลาดเคลื่อนได้

เนื่องจากข้อกำหนดเดียวกันยังขับเคลื่อนการทดสอบและการจำลองของ Apidog คุณจึงไม่ต้องบำรุงรักษาคำอธิบายสามอย่างสำหรับ API หนึ่งตัว คุณอธิบายเพียงครั้งเดียวแล้วนำกลับมาใช้ใหม่ได้

คำแนะนำ: จากข้อกำหนดสู่ URL ที่แชร์ได้

นี่คือเวอร์ชันย่อของการเผยแพร่เอกสารจากข้อกำหนด OpenAPI

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

การทำให้เอกสารซิงค์อยู่เสมอเมื่อข้อกำหนดเปลี่ยนแปลง

URL เอกสารจะมีประโยชน์ก็ต่อเมื่อมันยังคงถูกต้องอยู่เสมอ ปัญหาของการตั้งค่าชั่วคราวคือเมื่อมีคนปรับเปลี่ยน endpoint และลืมอัปเดตเอกสาร

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

นี่คือผลตอบแทนในทางปฏิบัติของหลักการ "docs-as-code": ความถูกต้องกลายเป็นผลพลอยได้จากเวิร์กโฟลว์ที่คุณต้องการอยู่แล้ว แทนที่จะเป็นงานที่แยกต่างหากที่ต้องอาศัยวินัย

คำถามที่พบบ่อย

Bruno สามารถสร้างและโฮสต์เอกสาร API สาธารณะได้หรือไม่?

Bruno มีไฟล์คอลเลกชัน .bru ที่อ่านได้และมุมมองเอกสาร Markdown ในแอป ซึ่งทั้งคู่ได้รับการตรวจสอบใน Git อย่างไรก็ตาม ไม่มีพอร์ทัลเอกสารสาธารณะที่โฮสต์และสร้างอัตโนมัติพร้อม URL ที่สามารถแชร์ได้ เพื่อเผยแพร่เอกสารสาธารณะจาก Bruno โดยทั่วไปทีมงานจะส่งออกข้อกำหนดและเรียกใช้เครื่องมือสร้างเอกสารแบบคงที่แยกต่างหาก ซึ่งจะเพิ่มไปป์ไลน์ที่ต้องบำรุงรักษา

ฉันจะได้รับ URL เอกสารที่สามารถแชร์ได้จาก API ของฉันได้อย่างไร?

อธิบาย API ของคุณในข้อกำหนด OpenAPI จากนั้นใช้เครื่องมือที่สร้างเอกสารที่โฮสต์จากข้อกำหนดนั้น ใน Apidog คุณนำเข้าข้อกำหนด กำหนดการมองเห็น เลือกแนบโดเมนที่กำหนดเองได้ และเผยแพร่ ผลลัพธ์คือเว็บไซต์เอกสารที่ใช้งานได้จริงบน URL ที่เสถียร พร้อมแผง "ลองใช้" แบบโต้ตอบ ที่คุณสามารถแชร์ได้โดยตรง

ฉันต้องทิ้งคอลเลกชัน Bruno ของฉันเพื่อเผยแพร่เอกสารหรือไม่?

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