วิธี ย้ายจาก Swagger CLI ไปยัง Apidog CLI

หากคุณยังคงเรียกใช้ swagger-cli validate และ swagger-cli bundle ในไปป์ไลน์ของคุณ นั่นหมายความว่าคุณกำลังดูแลสคริปต์ที่ใช้งานเครื่องมือที่ไม่มีใครดูแลอีกต่อไป ที่เก็บ GitHub ของ swagger-cli ตอนนี้ระบุไว้อย่างชัดเจนว่า: แพ็คเกจนี้ไม่ได้รับการดูแลอีกต่อไป ไฟล์ README อ้างถึงภาระในการติดตามผู้ใช้จำนวนมากที่ให้ผลตอบแทนน้อย และยังแนะนำผู้ใช้ใหม่ให้ไปใช้เครื่องมืออื่น

นี่จึงเป็นช่วงเวลาที่ดีในการตัดสินใจว่าขั้นตอนการทำงานของสเปคของคุณจะอยู่ที่ใดต่อไป คู่มือนี้เป็นคู่มือการย้ายข้อมูล ไม่ใช่บทช่วยสอนการใช้งาน หากคุณยังไม่พร้อมที่จะย้ายและเพียงแค่ต้องการใช้เครื่องมือเก่าต่อไป คู่มือ Swagger CLI ครอบคลุม validate และ bundle โดยละเอียด บทความนี้เกี่ยวกับการย้ายออก โดยเฉพาะอย่างยิ่งวิธีการย้าย Swagger CLI ไปยัง Apidog CLI โดยไม่กระทบ CI ของคุณ

ดาวน์โหลด Apidog หากคุณต้องการทำตามพร้อมคำสั่งจริง สามารถเริ่มต้นได้ฟรี ไม่ต้องใช้บัตรเครดิต

button

ทำไมต้องย้ายตอนนี้

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

พวกเขาชี้ไปที่ผู้สืบทอดคนหนึ่งโดยเฉพาะ Redocly CLI คือตัวตายตัวแทนที่ใกล้เคียงที่สุด หากสิ่งที่คุณต้องการคือ validate และ bundle ในเทอร์มินัลเท่านั้น มันเป็นโอเพนซอร์ส, เน้นโค้ดเป็นหลัก, และใช้งานได้ดีในเทอร์มินัล คำสั่ง lint ของมันทำการตรวจสอบโครงสร้าง และ redocly bundle ทำตามตัวชี้ $ref ได้อย่างแม่นยำเหมือนที่ swagger-cli bundle ทำ หากเป้าหมายเดียวของคุณคือการสลับแบบ 1:1 ที่เก็บสเปคเป็นไฟล์แบนในที่เก็บของคุณ Redocly คือทางเลือกที่เป็นธรรมชาติ และ Redocly ก็เผยแพร่ คู่มือการย้ายข้อมูลของตนเอง พร้อมแผนที่คำสั่ง ไม่มีอะไรน่าอายในการเลือกเส้นทางนั้น

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

เลือกจากความเหมาะสม ไม่ใช่กระแส หากคุณต้องการเครื่องมือ lint และ bundler ที่น้ำหนักเบา ขับเคลื่อนด้วยการตั้งค่า และคุณเรียกใช้จากเทอร์มินัลเท่านั้น Redocly ชนะ หากคุณต้องการแพลตฟอร์มเดียวสำหรับการออกแบบ, การจำลอง, การทดสอบ, และเอกสาร แทนที่จะต้องนำเครื่องมือหลายตัวมารวมกัน Apidog ชนะ

สิ่งที่ swagger-cli ทำ กับสิ่งที่ Apidog CLI ทำ

swagger-cli มีคำสั่งเพียงสองคำสั่งเท่านั้น:

swagger-cli validate <file> ตรวจสอบเอกสาร Swagger 2.0 หรือ OpenAPI 3.0 กับสคีมาและยืนยันว่าตัวชี้ $ref ของมันได้รับการแก้ไขแล้ว
swagger-cli bundle <file> ทำตามตัวชี้ $ref เหล่านั้นและรวมคำนิยามหลายไฟล์เข้าเป็นไฟล์เดียว พร้อมตัวเลือกสำหรับพาธเอาต์พุต (-o), ชนิด (-t json|yaml), การยกเลิกการอ้างอิงทั้งหมด (-r), และการเยื้อง (-f)

นั่นคือเครื่องมือทั้งหมด มันไม่ได้ lint ด้วยกฎสไตล์, สร้างเอกสาร, รันการทดสอบ, หรือจำลองอะไรเลย

Apidog CLI จัดการงานสองอย่างนั้นเข้ากับคำสั่งสองคำสั่งของมัน แล้วยังไปต่ออีก:

apidog import นำคำนิยามเข้าสู่โปรเจกต์ Apidog และตรวจสอบมันขณะนำเข้า สเปคหลายไฟล์ที่มีตัวชี้ $ref จะได้รับการแก้ไขเป็นทรัพยากรที่รวมกันโดยอัตโนมัติ นี่คือขั้นตอนการตรวจสอบของคุณ รวมถึงการนำเข้าด้วย
apidog export ส่งออกไฟล์เดียวที่รวมเข้าด้วยกันจากโปรเจกต์ และให้คุณเลือกเวอร์ชัน OpenAPI เมื่อส่งออก นี่คือขั้นตอนการรวมของคุณ รวมถึงการอัปเกรดเวอร์ชันเสริมและความสามารถในการส่งออกเอกสาร HTML หรือ Markdown
apidog run รันสถานการณ์และชุดทดสอบ พร้อมรายงาน JUnit และอื่นๆ สำหรับ CI swagger-cli ไม่มีสิ่งเทียบเท่านี้
คำสั่งทรัพยากร (endpoint, schema, mock, environment, branch, และอื่นๆ) จัดการโปรเจกต์จากเทอร์มินัลเมื่อสเปคอยู่ในนั้น

ข้อสังเกตที่แม่นยำเพื่อให้การแมปยังคงถูกต้อง: Apidog ตรวจสอบโครงสร้างเมื่อนำเข้า แต่ไม่ใช่ linter แบบกำหนดเองที่สามารถปรับแต่งกฎสไตล์ได้ ไม่มี apidog lint และไม่มีชุดกฎที่กำหนดเอง หากคุณพึ่งพาการ linting ที่มีทัศนคติเฉพาะ ส่วนนั้นจะไม่มีการส่งต่อ และส่วน สิ่งที่คุณจะได้รับเพิ่มเติมจากการตรวจสอบและรวม ครอบคลุมวิธีการจัดการ

ติดตั้งและเข้าสู่ระบบ

Apidog CLI มาในรูปแบบแพ็คเกจ npm ติดตั้งทั่วโลก:

npm install -g apidog-cli@latest

จากนั้นยืนยันตัวตนด้วยโทเค็นการเข้าถึง:

apidog login --with-token <TOKEN>

คุณจะได้รับโทเค็นจากแอป Apidog หรือเว็บ: คลิกอวตารของคุณ, ไปที่ Account Settings, จากนั้น API Access Token, และสร้างโทเค็น CLI จะจัดเก็บไว้ใน ~/.apidog/config.toml ปฏิบัติต่อมันเหมือนความลับอื่นๆ อย่าพิมพ์ลงในบันทึกหรือคอมมิตเข้าสู่ที่เก็บของคุณ

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

ตารางการแมปคำสั่ง

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

คำสั่ง swagger-cli	คำสั่ง Apidog CLI ที่เทียบเท่า	สิ่งที่เปลี่ยนแปลง
`swagger-cli validate openapi.yaml`	`apidog import --project <id> --format openapi --file ./openapi.yaml`	ตรวจสอบสเปคเมื่อนำเข้า; สเปคที่ไม่ถูกต้องจะทำให้คำสั่งล้มเหลว
`swagger-cli bundle openapi.yaml -o out.json`	`apidog import ...` จากนั้น `apidog export --project <id> --format openapi --output ./out.json`	การรวมกลายเป็นการส่งออกจากโปรเจกต์; `$refs` ได้รับการแก้ไขแล้วเมื่อนำเข้า
`swagger-cli bundle -t yaml`	`apidog export --project <id> --format openapi --output ./out.yaml`	รูปแบบเอาต์พุตตามไฟล์ที่คุณเขียน
(ไม่มีสิ่งเทียบเท่า)	`apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1`	อัปเกรดสเปค 2.0 หรือ 3.0 เป็น 3.1 เมื่อส่งออก
(ไม่มีสิ่งเทียบเท่า)	`apidog export --project <id> --format html --output ./docs.html`	ส่งออกเอกสาร HTML แบบสแตนด์อโลน
(ไม่มีสิ่งเทียบเท่า)	`apidog export --project <id> --format markdown --output ./docs.md`	ส่งออกเอกสาร Markdown
(ไม่มีสิ่งเทียบเท่า)	`apidog run --project <id> -t <scenarioId> -e <envId> -r junit`	รันการทดสอบ API ใน CI

เซลล์สองเซลล์ที่สำคัญที่สุดสำหรับการย้ายข้อมูลคือสองแถวแรก ทุกอย่างที่อยู่ด้านล่างนั้นคือความสามารถที่ swagger-cli ไม่เคยมี แฟล็ก --oas-version คือการอัปเกรดที่ชัดเจนที่สุด: swagger-cli สามารถรวมไฟล์ Swagger 2.0 ได้ แต่ไม่สามารถแปลงเป็น OpenAPI 3.1 ได้ Apidog ทำได้เมื่อส่งออก ซึ่งมีประโยชน์เมื่อคุณกำลังปรับปรุงสัญญาเก่า หากเป้าหมายของคุณคือการส่งออกเอกสารโดยเฉพาะ การส่งออก OpenAPI เป็น Markdown จะอธิบายรูปแบบนั้นในเชิงลึกมากขึ้น

การย้ายข้อมูลทีละขั้นตอน

นี่คือเส้นทางทั้งหมดจากการตั้งค่า swagger-cli ไปยังโฟลว์การทำงานของ Apidog

1. รับรหัสโปรเจกต์ของคุณ สร้างหรือเปิดโปรเจกต์ในแอป Apidog รหัสโปรเจกต์จะปรากฏในการตั้งค่าโปรเจกต์และใน URL คุณจะต้องส่งรหัสนี้ไปยังทุกคำสั่ง CLI ผ่าน --project

2. นำเข้าสเปคหลัก ชี้ Apidog ไปยังไฟล์เริ่มต้นของคำนิยามของคุณ สเปคหลายไฟล์ที่มีตัวชี้ $ref จะได้รับการแก้ไขโดยอัตโนมัติ ดังนั้นคุณจะนำเข้าไฟล์หลักและ Apidog จะดึงส่วนที่เหลือเข้ามา:

apidog import --project 123456 --format openapi --file ./openapi.yaml

หากสเปคมีข้อผิดพลาดหรือ $ref ค้างอยู่ การนำเข้าจะล้มเหลว ความล้มเหลวนั้นคือประตูการตรวจสอบของคุณ ซึ่งเป็นงานเดียวกับที่ swagger-cli validate เคยทำ ตอนนี้ได้ถูกรวมเข้ากับการนำเข้าแล้ว

3. ตรวจสอบในแอป เปิดโปรเจกต์และยืนยันว่า endpoints, schemas และ parameters ของคุณถูกนำเข้าอย่างถูกต้อง การตรวจสอบด้วยสายตานี้ไม่มีสิ่งที่เทียบเท่าใน swagger-cli และคุ้มค่าที่จะทำเพียงครั้งเดียวระหว่างการย้ายข้อมูลเพื่อยืนยันว่าการนำเข้าเป็นไปตามที่คุณคาดหวัง

4. ส่งออกไฟล์ที่รวมเข้าด้วยกัน เมื่อคุณต้องการไฟล์แบนเพียงไฟล์เดียว (สำหรับเครื่องมือปลายน้ำ, ตัวสร้างไคลเอ็นต์ หรืออาร์ติแฟกต์) ให้ส่งออกมัน เลือกเวอร์ชัน OpenAPI ที่คุณต้องการ:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

สิ่งนี้จะมาแทนที่ swagger-cli bundle ตัวชี้ $ref ได้รับการแก้ไขแล้วเมื่อนำเข้า ดังนั้นการส่งออกคือเอาต์พุตไฟล์เดียวที่รวมเข้าด้วยกันของคุณ

5. เชื่อมต่อเข้ากับ CI แทนที่ขั้นตอน swagger-cli เก่าของคุณด้วยการนำเข้า (ตรวจสอบเมื่อนำเข้า) และการส่งออก (รวม), และเพิ่มการทดสอบหากคุณมีสถานการณ์ ส่วนถัดไปมีตัวอย่าง GitHub Actions ฉบับเต็ม

ตัวอย่าง CI ด้วย GitHub Actions

เวิร์กโฟลว์นี้จะติดตั้ง CLI, เข้าสู่ระบบด้วยโทเค็นจากความลับของที่เก็บ, นำเข้าสเปคเพื่อตรวจสอบ, ส่งออกอาร์ติแฟกต์ที่รวมเข้าด้วยกัน, จากนั้นรันสถานการณ์การทดสอบด้วย JUnit reporter เพื่อให้การทดสอบที่ล้มเหลวทำให้การตรวจสอบล้มเหลวและบล็อก PR

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

เก็บโทเค็นเป็น APIDOG_ACCESS_TOKEN ในความลับของที่เก็บของคุณ เพื่อไม่ให้ปรากฏในบันทึก รายงาน -r "cli,junit" จะเขียนไฟล์ JUnit XML ที่ CI ของคุณสามารถแสดงเป็นรายงานการทดสอบได้ และสถานการณ์ที่ล้มเหลวจะคืนค่ารหัสการออกที่ไม่ใช่ศูนย์ซึ่งจะบล็อกการรวม สำหรับรูปแบบไปป์ไลน์ที่ลึกซึ้งยิ่งขึ้น โปรดดูที่ คู่มือ CI/CD ของ Apidog CLI และสำหรับการตั้งค่าเฉพาะของรันเนอร์ โปรดดูที่ การใช้งาน Apidog CLI ร่วมกับ GitHub Actions

สิ่งที่คุณจะได้รับเพิ่มเติมจากการตรวจสอบและรวม

นี่คือจุดที่การย้ายข้อมูลจะได้รับผลตอบแทน และเป็นจุดที่ความซื่อสัตย์มีความสำคัญมากที่สุด

เซิร์ฟเวอร์จำลอง (Mock servers) เมื่อสเปคของคุณอยู่ในโปรเจกต์แล้ว Apidog สามารถให้บริการตอบกลับแบบจำลองจากมันได้ คุณสามารถพัฒนาส่วนหน้าของแอปพลิเคชันโดยอ้างอิงจาก API ก่อนที่ส่วนหลังจะถูกสร้างขึ้นด้วยซ้ำ swagger-cli ไม่เคยแตะพฤติกรรมการรันไทม์

สถานการณ์การทดสอบอัตโนมัติ apidog run จะดำเนินการคำขอจริงกับ API ที่กำลังทำงานอยู่และยืนยันการตอบกลับ คุณสร้างสถานการณ์ด้วยภาพในแอป แล้วรันแบบ Headless ใน CI สิ่งนี้จะปิดช่องว่างที่ swagger-cli เปิดทิ้งไว้: สเปคที่ถูกต้องจะบอกคุณว่าสัญญาถูกสร้างขึ้นอย่างดี แต่ไม่ได้บอกว่าการใช้งานตรงกับสัญญานั้นหรือไม่

เอกสารที่โฮสต์และส่งออก apidog export --format html หรือ --format markdown จะสร้างเอกสารโดยตรงจากแหล่งเดียวกัน ไม่ต้องมีขั้นตอนการสร้างเอกสารแยกต่างหากให้ต้องดูแล

มาถึงข้อจำกัดที่ตรงไปตรงมา: Apidog CLI ไม่มี Linter สไตล์โค้ดแบบกำหนดค่าได้พร้อมชุดกฎที่กำหนดเอง มันตรวจสอบโครงสร้างเมื่อนำเข้า แต่คุณไม่สามารถเขียนกฎสไตล์ Spectral หรือ Redocly ผ่าน CLI ได้ และไม่มีคำสั่ง apidog lint หากการตั้งค่าเก่าของคุณพึ่งพาการ Linter อย่างหนัก (การตั้งชื่อที่สอดคล้องกัน, คำอธิบายที่จำเป็น, ตัวอย่างในทุกการตอบกลับ) ให้เก็บ Linter เฉพาะทางไว้ในกระบวนการ จับคู่ Apidog กับ Spectral หรือ Redocly สำหรับสิ่งนั้น และรันเป็นขั้นตอน CI แยกต่างหาก คู่มือการตั้งค่า OpenAPI linter ครอบคลุมวิธีการเชื่อมต่อ การใช้ทั้งสองอย่างไม่ใช่ความขัดแย้ง: Linter ด้วยเครื่องมือผู้เชี่ยวชาญ จากนั้นจัดการวงจรชีวิตใน Apidog

button