วิธีจัดทำเอกสาร API ผ่าน CLI

เอกสาร API จะล้าสมัยทันทีที่มีคนแก้ไขสเปคแล้วลืมสร้างเอกสารอ้างอิงใหม่ วิธีแก้คือเลิกมองว่าการจัดทำเอกสารเป็นขั้นตอนที่ต้องทำด้วยตนเอง หากคุณสามารถสร้างเอกสารได้ด้วยคำสั่งเดียว คุณก็สามารถผสานคำสั่งนั้นเข้ากับ CI และให้มันทำงานทุกครั้งที่มีการรวมโค้ด (merge) ได้

การทำจากเทอร์มินัลก็มีข้อดีอื่นๆ อีก คำสั่งสามารถเขียนสคริปต์ได้ ทิ้งส่วนต่าง (diff) ที่คุณสามารถตรวจสอบได้ และตัวแทน AI หรือ CI runner สามารถเรียกใช้ได้โดยไม่ต้องมีใครเปิดเบราว์เซอร์ ไม่ต้องคลิก GUI ไม่ต้อง "จำได้ไหมว่ากดส่งออกแล้วหรือยัง"

คู่มือนี้จะนำเสนอเส้นทางทั่วไปก่อน: การเปลี่ยนไฟล์ OpenAPI ให้เป็นเอกสารอ้างอิง HTML แบบสแตนด์อโลน หรือไฟล์ Markdown ด้วยคำสั่งเดียว จากนั้นจะเจาะลึกเส้นทาง Apidog CLI ซึ่งดึงเอกสารของคุณออกมาจากโปรเจกต์ที่ใช้งานจริงโดยตรง เพื่อให้แหล่งข้อมูลจริงและผลลัพธ์ยังคงสอดคล้องกัน หากคุณต้องการข้อมูลเพิ่มเติมเกี่ยวกับภาพรวม โปรดดูสรุป เครื่องมือจัดทำเอกสาร REST API ยอดนิยม และ เครื่องมือจัดทำเอกสาร API ฟรี ที่ควรรู้ของเรา

คุณต้องการสิ่งเดียวในการทำตาม: ไฟล์ OpenAPI 3.x คำสั่งส่วนใหญ่ยอมรับ openapi.yaml หรือ openapi.json ได้เหมือนกัน

สร้างเอกสารอ้างอิง HTML ด้วย Redocly CLI

Redocly CLI เป็นวิธีที่รวดเร็วที่สุดในการเปลี่ยนคำอธิบาย OpenAPI ให้เป็นหน้า HTML ที่สมบูรณ์และเป็นอิสระในตัว มันจะแสดงผลสเปคของคุณด้วย Redoc และเขียนทุกอย่าง (สไตล์ สคริปต์ และเนื้อหา) ลงในไฟล์เดียวที่คุณสามารถโฮสต์ได้ทุกที่หรือส่งอีเมลให้เพื่อนร่วมทีม

ติดตั้งแบบ Global หรือข้ามการติดตั้งแล้วรันด้วย npx:

npm install @redocly/cli -g

จากนั้นชี้ไปที่สเปคของคุณ:

redocly build-docs openapi.yaml

โดยค่าเริ่มต้น นี่จะเขียน redoc-static.html ในไดเรกทอรีปัจจุบัน เปิดไฟล์นั้นในเบราว์เซอร์ แล้วคุณจะได้เอกสารอ้างอิง API แบบสามพาเนลที่สมบูรณ์ หากต้องการควบคุมชื่อไฟล์หรือพาธ ให้ใช้ --output:

redocly build-docs openapi.yaml --output docs/index.html

นั่นคือเวิร์กโฟลว์ทั้งหมด ไฟล์อินพุตเดียว คำสั่งเดียว ไฟล์ HTML ที่สร้างขึ้นเดียว มันใช้งานได้กับคำอธิบาย Swagger 2.0 และ OpenAPI 3.0/3.1 ดังนั้นสเปคที่มีอยู่ส่วนใหญ่จึงสามารถแสดงผลได้โดยไม่ต้องเปลี่ยนแปลง ข้อแลกเปลี่ยนคือขอบเขต: build-docs ให้หน้าอ้างอิงและไม่มีอะไรอื่น คู่มือแบบยาว บทช่วยสอน และหน้าเริ่มต้นใช้งานจะอยู่นอกเหนือจากนี้

สร้าง Markdown ด้วย Widdershins

บางครั้งคุณอาจไม่ต้องการ HTML คุณต้องการ Markdown ที่สามารถนำไปใส่ในไซต์เอกสาร, ตัวสร้างไซต์แบบคงที่, หรือโฟลเดอร์ docs/ ของ repo Widdershins แปลงคำจำกัดความ OpenAPI, Swagger, หรือ AsyncAPI ให้เป็น Markdown ที่เข้ากันได้กับ Slate

ติดตั้งจาก npm:

npm install -g widdershins

จากนั้นแปลงสเปคของคุณ โดยส่งเอาต์พุตไปยังไฟล์ด้วย -o:

widdershins openapi.yaml -o api.md

หากไม่ใส่ -o Widdershins จะพิมพ์ออกไปยัง stdout ซึ่งสะดวกหากคุณต้องการส่งต่อไปยังที่อื่น คุณยังสามารถสลับแท็บภาษาสำหรับตัวอย่างโค้ดได้:

widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md

Widdershins เหมาะสมอย่างยิ่งเมื่อไปป์ไลน์เอกสารของคุณเน้น Markdown เป็นหลัก หากคุณกำลังสร้างกระบวนการส่งออก Markdown ที่กว้างขึ้น คู่มือของเราเกี่ยวกับการใช้ ตัวสร้างเอกสาร API พร้อมการส่งออก Markdown จะครอบคลุมเครื่องมือที่เกี่ยวข้อง ข้อจำกัดของทั้ง Redocly และ Widdershins เหมือนกัน: พวกมันอ่านไฟล์แบบคงที่ หากคำจำกัดความ API ของคุณอยู่ในเครื่องมือออกแบบและแตกต่างจากไฟล์บนดิสก์ คุณกำลังจัดทำเอกสารสำหรับสเปคของเมื่อวาน

จัดทำเอกสารจากโปรเจกต์จริงด้วย Apidog CLI

นี่คือจุดที่เส้นทางแบบบูรณาการให้ผลตอบแทน Apidog ไม่ใช่โอเพนซอร์ส แต่เวอร์ชันฟรีบวกกับ apidog-cli ให้ทางเลือกในการรวมเครื่องมือที่แยกกัน: ปลายทางของคุณ สคีมา และเอกสารที่เขียนไว้ทั้งหมดอยู่ในโปรเจกต์เดียว และ CLI จะส่งออกจากโปรเจกต์นั้นตามต้องการ ไม่มีอะไรคลาดเคลื่อน เพราะการส่งออกอ่านจากแหล่งข้อมูลเดียวกับที่ทีมของคุณแก้ไข

ติดตั้ง CLI จาก npm:

npm install -g apidog-cli

หากคุณกำลังตั้งค่าเป็นครั้งแรก คู่มือการติดตั้ง Apidog CLI ของเราจะครอบคลุมเวอร์ชัน Node และการตั้งค่า PATH จากนั้นทำการรับรองความถูกต้อง (authenticate) เพียงครั้งเดียวด้วยโทเค็นการเข้าถึงส่วนบุคคล:

apidog login --with-token <TOKEN>

โทเค็นจะถูกจัดเก็บ ดังนั้นคุณไม่จำเป็นต้องส่งไปพร้อมกับการเรียกใช้ทุกครั้ง จากจุดนี้ ทุกอย่างจะทำงานกับ ID โปรเจกต์ เพิ่ม --help ในคำสั่งใดๆ เพื่อดูแฟล็กที่ถูกต้องก่อนที่จะรัน

นำเข้าสเปคเข้าสู่โปรเจกต์

หาก API ของคุณอยู่ในไฟล์ OpenAPI อยู่แล้ว ให้นำเข้าสู่โปรเจกต์เพื่อให้ CLI มีสิ่งที่จะส่งออก:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json

apidog import ยอมรับรูปแบบ OpenAPI 3.x, Swagger 2.0, Postman และ Apidog ดังนั้นคุณสามารถดึงคอลเล็กชัน Postman หรือไฟล์ Apidog ที่ส่งออกอยู่แล้วได้ด้วยวิธีเดียวกัน เมื่อนำเข้าสเปคแล้ว มันจะกลายเป็นแหล่งข้อมูลจริงที่ทุกอย่างอ่านจาก

ส่งออกเอกสารที่มนุษย์อ่านได้

นี่คือคำสั่งหลัก apidog export เขียน OpenAPI, HTML, Markdown หรือ Postman ดังนั้นให้รัน --help ก่อนเพื่อดูรูปแบบและแฟล็กเอาต์พุตที่ถูกต้องสำหรับเวอร์ชันของคุณ จากนั้นส่งออกเอกสารของโปรเจกต์เป็น Markdown:

apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md

เปิด api-docs.md แล้วคุณจะได้เอกสารอ้างอิงฉบับสมบูรณ์ที่สร้างขึ้นจากสถานะปัจจุบันของโปรเจกต์ ต้องการ HTML แทนหรือไม่? เปลี่ยนแฟล็กเดียว:

apidog export --project <projectId> --format html --output ./api-docs.html

คุณยังสามารถส่งออกกลับไปยัง OpenAPI ได้เมื่อคุณต้องการสเปคที่สามารถพกพาได้เพื่อส่งต่อให้ขั้นตอนถัดไป:

apidog export --project <projectId> --format openapi --output ./openapi.json

หากโปรเจกต์ของคุณมีหลายบริการและคุณต้องการจัดทำเอกสารเพียงบางส่วน การส่งออกรองรับการจำกัดขอบเขต ตรวจสอบ apidog export --help สำหรับแฟล็กขอบเขตและ ID ในเวอร์ชันของคุณ เนื่องจากโปรเจกต์เดียวสามารถส่งไฟล์เอกสารหนึ่งไฟล์ต่อบริการได้ด้วยวิธีนั้น

จัดการคู่มือที่เป็นลายลักษณ์อักษร ไม่ใช่แค่เอกสารอ้างอิง

เอกสารอ้างอิงที่สร้างจากสคีมาของคุณเป็นเพียงครึ่งหนึ่งของเรื่องราว อีกครึ่งหนึ่งคือบทความ: คู่มือเริ่มต้นใช้งาน, คำแนะนำการยืนยันตัวตน, บันทึกการย้ายข้อมูล ใน Apidog สิ่งเหล่านี้จะอยู่ในโครงสร้างเอกสารของโปรเจกต์ในรูปแบบเอกสาร Markdown และ CLI จะจัดการสิ่งเหล่านี้ด้วยกลุ่มคำสั่ง doc

เริ่มต้นด้วยการอ่านความช่วยเหลือของกลุ่มคำสั่ง เพื่อให้คุณทำงานด้วยแฟล็กที่ถูกต้องตรงตามเวอร์ชันของคุณ:

apidog doc --help
apidog doc list --project <projectId>

จากจุดนั้น กระบวนการจะเหมือนกับส่วนอื่นๆ ใน CLI: รันคำสั่งกับโปรเจกต์ของคุณ, อ่านผลลัพธ์ JSON, และทำตาม agentHints.nextSteps ที่ส่งกลับมา เมื่อคำสั่งต้องการเพย์โหลด JSON CLI สามารถพิมพ์สคีมาที่คาดหวังและตรวจสอบไฟล์ของคุณกับสคีมานั้นก่อนที่คุณจะส่งอะไรออกไป เพื่อให้คุณตรวจพบฟิลด์ที่หายไปบนเครื่องของคุณแทนที่จะเป็นข้อผิดพลาดในการเรียกใช้ ตรวจสอบ apidog cli-schema --help สำหรับคำสั่งย่อย validate ที่ถูกต้อง

เผยแพร่ไซต์เอกสาร

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

apidog docs-site --help
apidog shared-doc --help

ข้อควรทราบเกี่ยวกับการตั้งชื่อที่มักทำให้คนสับสน: doc คือเอกสาร Markdown ภายในโครงสร้าง API ของโปรเจกต์, docs-site จัดการไซต์เอกสารสาธารณะที่โฮสต์ไว้, และ shared-doc จัดการลิงก์เอกสารที่สามารถแชร์ได้ ใช้ docs-site เมื่อคุณต้องการไซต์สาธารณะที่กำหนดจากเทอร์มินัลแทนการคลิกใน UI และ shared-doc เมื่อคุณต้องการเพียงแค่ลิงก์เพื่อส่งให้คู่ค้า ผลตอบแทนคือการเผยแพร่กลายเป็นขั้นตอนแบบสคริปต์: เมื่อสเปคของคุณเปลี่ยน คุณเพียงแค่นำเข้าใหม่หรือแก้ไขโปรเจกต์ จากนั้นรันคำสั่งเผยแพร่อีกครั้ง และเอกสารที่โฮสต์ไว้ก็จะสะท้อนการอัปเดต

เชื่อมต่อเข้ากับ CI

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

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md

สลับใช้ redocly build-docs หรือ widdershins และรูปแบบก็จะเหมือนกัน เอกสารจะเลิกเป็นงานจุกจิกที่ใครบางคนต้องจำทำ และกลายเป็นผลผลิตจากการบิลด์ที่สร้างขึ้นใหม่ได้เอง สำหรับข้อมูลอ้างอิงคำสั่งฉบับเต็ม โปรดดู คู่มือ Apidog CLI ฉบับสมบูรณ์

ปัญหาที่พบบ่อย

• Project ID ผิดหรือไม่ถูกต้อง ทุกการเรียกใช้ export, doc, และ docs-site ของ Apidog ต้องมี --project <projectId> ID จะอยู่ในส่วนการตั้งค่าโปรเจกต์ ไม่ใช่ชื่อโปรเจกต์ที่มนุษย์อ่านได้ หากคำสั่งเกิดข้อผิดพลาดเกี่ยวกับการร้องเรียนโปรเจกต์ นั่นมักจะเป็นสาเหตุเกือบทั้งหมด
• โทเค็นไม่ได้ตั้งค่าใน CI apidog login จัดเก็บโทเค็นบนเครื่องที่รันมัน ใน CI runner ที่ติดตั้งใหม่จะไม่มีโทเค็นที่จัดเก็บไว้ ดังนั้นคุณต้องรัน login --with-token ในงานเดียวกันก่อนการส่งออกใดๆ จัดเก็บโทเค็นเป็นความลับ ห้ามเก็บไว้ในไฟล์เวิร์กโฟลว์
• การส่งออกไฟล์เก่า Redocly และ Widdershins อ่านไฟล์ใดก็ตามที่คุณให้พวกมัน หาก openapi.yaml ของคุณล้าสมัย เอกสารของคุณก็ล้าสมัยด้วย นี่คือความคลาดเคลื่อนที่เส้นทาง Apidog หลีกเลี่ยงได้โดยการส่งออกจากโปรเจกต์ที่ใช้งานจริงแทนที่จะเป็นไฟล์บนดิสก์
• เดาแฟล็กแทนที่จะอ่าน --help แฟล็กที่ถูกต้องสำหรับ export, doc, docs-site, และ shared-doc อาจแตกต่างกันไปตามเวอร์ชันของ CLI รัน apidog <command> --help และใช้ข้อมูลที่มันแสดงผลแทนแฟล็กที่คุณจำได้ไม่แม่นยำ มันใช้เวลาเพียงสองวินาทีและช่วยป้องกันการบิลด์ที่ล้มเหลว

สรุป

การจัดทำเอกสาร API จากเทอร์มินัลนั้นอยู่ที่การเลือกเอาต์พุตที่เหมาะสม เลือกใช้ Redocly CLI เมื่อคุณต้องการเอกสารอ้างอิง HTML แบบสแตนด์อโลน, Widdershins เมื่อคุณต้องการ Markdown สำหรับไซต์เอกสาร, และ Apidog CLI เมื่อคุณต้องการเอกสารอ้างอิงรวมถึงคู่มือที่เป็นลายลักษณ์อักษรและไซต์ที่เผยแพร่ได้ทั้งหมด โดยส่งออกจากแหล่งข้อมูลที่ใช้งานจริงแหล่งเดียว ตัวเลือกสุดท้ายคือตัวเลือกที่ทำให้เอกสารของคุณมีความน่าเชื่อถือ เพราะการส่งออกและสิ่งที่ทีมของคุณแก้ไขนั้นมาจากโปรเจกต์เดียวกัน

ทุกคำสั่งที่นี่สามารถเขียนสคริปต์ได้ ซึ่งหมายความว่าทุกคำสั่งสามารถใช้ใน CI ได้ ตั้งค่าเพียงครั้งเดียวแล้วเอกสารของคุณจะสร้างขึ้นใหม่เองทุกครั้งที่มีการเปลี่ยนแปลง ดาวน์โหลด Apidog เพื่อรับ CLI และลองกระบวนการส่งออกกับโปรเจกต์ของคุณเอง หรืออ่านเพิ่มเติมว่า Apidog เข้ากับเวิร์กโฟลว์แบบ API-first ได้อย่างไร