DEV Community

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

Posted on • Originally published at apidog.com

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

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

ลองใช้ Apidog วันนี้

การทำจากเทอร์มินัลก็มีข้อดีอื่นๆ อีก คำสั่งสามารถเขียนสคริปต์ได้ ทิ้งส่วนต่าง (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:

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

จากนั้นสร้างเอกสารจากสเปค:

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

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

หากต้องการกำหนดตำแหน่งและชื่อไฟล์เอาต์พุต ให้ใช้ --output:

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

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

ข้อจำกัดคือ build-docs สร้างเฉพาะหน้าอ้างอิง API เท่านั้น คู่มือแบบยาว บทช่วยสอน และหน้าเริ่มต้นใช้งานต้องจัดการแยกต่างหาก

สร้าง Markdown ด้วย Widdershins

หากปลายทางของคุณคือไซต์เอกสาร ตัวสร้าง static site หรือโฟลเดอร์ docs/ ใน repository คุณอาจต้องการ Markdown แทน HTML

Widdershins แปลงคำจำกัดความ OpenAPI, Swagger หรือ AsyncAPI เป็น Markdown ที่เข้ากันได้กับ Slate

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

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

แปลงสเปคและเขียนผลลัพธ์ลงไฟล์ด้วย -o:

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

หากไม่ระบุ -o Widdershins จะพิมพ์ผลลัพธ์ไปยัง stdout ซึ่งเหมาะสำหรับการ pipe ต่อไปยังคำสั่งอื่น

ตัวอย่างการกำหนดแท็บภาษาสำหรับโค้ดตัวอย่าง:

widdershins openapi.yaml \
  --language_tabs 'shell:cURL' 'python:Python' \
  -o api.md
Enter fullscreen mode Exit fullscreen mode

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

ข้อจำกัดของ Redocly และ Widdershins เหมือนกัน: ทั้งคู่สร้างเอกสารจากไฟล์แบบคงที่ หาก openapi.yaml บนดิสก์ล้าสมัย เอกสารที่ได้ก็จะล้าสมัยตามไปด้วย

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

หากต้องการลดความเสี่ยงที่สเปคกับเอกสารจะไม่ตรงกัน ให้ส่งออกจากโปรเจกต์ที่ทีมใช้งานจริงโดยตรง

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

ติดตั้ง CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

หากตั้งค่าเป็นครั้งแรก ดู คู่มือการติดตั้ง Apidog CLI สำหรับข้อกำหนดของ Node และการตั้งค่า PATH

เข้าสู่ระบบด้วย Personal Access Token:

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

CLI จะจัดเก็บโทเค็นไว้ จึงไม่ต้องส่งโทเค็นในทุกคำสั่ง หลังจากนี้ให้ทำงานผ่าน Project ID และตรวจสอบแฟล็กของคำสั่งด้วย --help ก่อนใช้งาน

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

หาก API อยู่ในไฟล์ OpenAPI แล้ว ให้นำเข้าสู่โปรเจกต์ก่อน:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

apidog import รองรับ OpenAPI 3.x, Swagger 2.0, Postman และ Apidog เมื่อสเปคถูกนำเข้าแล้ว สเปคนั้นจะเป็นแหล่งข้อมูลที่ CLI ใช้สำหรับการส่งออก

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

คำสั่งหลักคือ apidog export ซึ่งรองรับการส่งออกเป็น OpenAPI, HTML, Markdown และ Postman

ตรวจสอบรูปแบบและแฟล็กของ CLI เวอร์ชันที่คุณใช้งานก่อน:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

ส่งออกเอกสารของโปรเจกต์เป็น Markdown:

apidog export \
  --project <projectId> \
  --format markdown \
  --output ./api-docs.md
Enter fullscreen mode Exit fullscreen mode

เปิด api-docs.md เพื่อดูเอกสารอ้างอิงที่สร้างจากสถานะปัจจุบันของโปรเจกต์

หากต้องการ HTML ให้เปลี่ยนเฉพาะรูปแบบเอาต์พุต:

apidog export \
  --project <projectId> \
  --format html \
  --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

หากต้องการ OpenAPI แบบพกพาเพื่อนำไปใช้ในขั้นตอนถัดไป:

apidog export \
  --project <projectId> \
  --format openapi \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

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

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

เอกสารอ้างอิงจากสคีมาเป็นเพียงส่วนหนึ่งของเอกสาร API ยังมีคู่มือเริ่มต้นใช้งาน คำแนะนำการยืนยันตัวตน และบันทึกการย้ายข้อมูล

ใน Apidog เอกสารเหล่านี้อยู่ในโครงสร้างเอกสารของโปรเจกต์ในรูปแบบ Markdown และจัดการผ่านกลุ่มคำสั่ง doc

เริ่มด้วยการตรวจสอบคำสั่งที่ใช้ได้:

apidog doc --help
apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

กระบวนการทำงานคือรันคำสั่งกับโปรเจกต์ อ่านผลลัพธ์ JSON และทำตาม agentHints.nextSteps ที่คำสั่งส่งกลับมา

เมื่อคำสั่งต้องใช้ JSON payload คุณสามารถดูสคีมาที่ CLI คาดหวังและตรวจสอบไฟล์ในเครื่องก่อนส่งคำขอได้ ตรวจสอบคำสั่งที่รองรับผ่าน:

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

โดยเฉพาะคำสั่งย่อย validate ที่ตรงกับ CLI เวอร์ชันของคุณ

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

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

เริ่มจากดูคำสั่งที่รองรับ:

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

ความหมายของแต่ละกลุ่มคำสั่งมีดังนี้:

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

ใช้ docs-site เมื่อต้องการกำหนดหรืออัปเดตไซต์สาธารณะจากเทอร์มินัล และใช้ shared-doc เมื่อต้องการลิงก์สำหรับส่งให้คู่ค้าหรือผู้ใช้งาน

ผลลัพธ์คือการเผยแพร่กลายเป็นขั้นตอนที่เขียนสคริปต์ได้: แก้ไขสเปคหรือนำเข้าสเปคใหม่ แล้วรันคำสั่งเผยแพร่อีกครั้งเพื่อให้เอกสารที่โฮสต์สะท้อนการเปลี่ยนแปลง

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

ข้อดีหลักของ CLI คือความสามารถในการทำซ้ำ เมื่อคำสั่งทำงานได้บนเครื่องนักพัฒนา ก็มักนำไปใช้ใน pipeline ได้โดยตรง

ตัวอย่าง GitHub Actions ที่ส่งออกเอกสาร Markdown ทุกครั้งที่มีการ push:

- 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
Enter fullscreen mode Exit fullscreen mode

หากใช้ Redocly หรือ Widdershins รูปแบบของขั้นตอนก็เหมือนกัน เพียงเปลี่ยนคำสั่งสร้างเอกสาร เช่น:

- name: Build HTML API docs
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

หรือ:

- name: Generate Markdown API docs
  run: |
    npm install -g widdershins
    widdershins openapi.yaml -o docs/api.md
Enter fullscreen mode Exit fullscreen mode

เมื่อใส่ขั้นตอนเหล่านี้ใน CI เอกสารจะกลายเป็นผลลัพธ์จาก build แทนงานที่ต้องรอให้ใครสักคนจำทำเอง

สำหรับรายการคำสั่งเพิ่มเติม ดู คู่มือ Apidog CLI ฉบับสมบูรณ์

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

  • Project ID ผิดหรือไม่ถูกต้อง

    ทุกการเรียกใช้ export, doc และ docs-site ของ Apidog ต้องระบุ --project <projectId> ใช้ ID จากการตั้งค่าโปรเจกต์ ไม่ใช่ชื่อโปรเจกต์ที่มนุษย์อ่านได้

  • โทเค็นไม่ได้ตั้งค่าใน CI

    apidog login จัดเก็บโทเค็นบนเครื่องที่รันคำสั่ง แต่ CI runner ใหม่ไม่มีโทเค็นเดิมอยู่แล้ว ดังนั้นให้รัน login --with-token ใน job เดียวกันก่อนส่งออกเอกสาร เก็บโทเค็นไว้ใน secrets และอย่าใส่ลงในไฟล์ workflow

  • ส่งออกจากไฟล์เก่า

    Redocly และ Widdershins อ่านไฟล์ที่คุณส่งให้โดยตรง หาก openapi.yaml ไม่อัปเดต เอกสารก็จะไม่อัปเดตด้วย การส่งออกจากโปรเจกต์ Apidog ช่วยลดความคลาดเคลื่อนนี้ได้ เพราะ CLI อ่านจากโปรเจกต์ที่ใช้งานจริง

  • เดาแฟล็กแทนที่จะอ่าน --help

    แฟล็กของ export, doc, docs-site และ shared-doc อาจต่างกันตามเวอร์ชันของ CLI ให้รันคำสั่งต่อไปนี้ก่อนใช้งานเสมอ:

  apidog <command> --help
Enter fullscreen mode Exit fullscreen mode

ใช้แฟล็กที่ CLI แสดงผล แทนการอ้างอิงคำสั่งที่จำได้จากเวอร์ชันก่อนหน้า

สรุป

การจัดทำเอกสาร API จากเทอร์มินัลเริ่มจากการเลือกเอาต์พุตที่ต้องการ:

  • ใช้ Redocly CLI เมื่อต้องการเอกสารอ้างอิง HTML แบบสแตนด์อโลน
  • ใช้ Widdershins เมื่อต้องการ Markdown สำหรับไซต์เอกสารหรือ repository
  • ใช้ Apidog CLI เมื่อต้องการส่งออกเอกสารอ้างอิง คู่มือ Markdown และจัดการไซต์เอกสารจากโปรเจกต์เดียว

ทุกคำสั่งในบทความนี้เขียนสคริปต์และใช้กับ CI ได้ ตั้งค่าเพียงครั้งเดียว แล้วให้เอกสารสร้างใหม่ทุกครั้งที่ API เปลี่ยนแปลง

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

Top comments (0)