วิศวกรสองคนในทีมเดียวกันได้ปล่อยใช้งานสองเอนด์พอยต์ในสัปดาห์เดียวกัน เอนด์พอยต์หนึ่งคืนค่า created_at ส่วนอีกเอนด์พอยต์หนึ่งคืนค่า createdAt เอนด์พอยต์หนึ่งใช้การแบ่งหน้าด้วย ?page= ส่วนอีกเอนด์พอยต์หนึ่งใช้ ?offset= ซึ่งแต่ละแบบก็ไม่ได้ผิดในตัวเอง แต่เมื่อนำมารวมกันแล้วจะทำให้ API ของคุณรู้สึกเหมือนถูกสร้างขึ้นโดยคนแปลกหน้า และลูกค้าทุกคนที่ใช้ API นั้นก็ต้องแบกรับภาระนี้ ไฟล์ OpenAPI สามารถตรวจสอบความถูกต้องได้ดี มันสามารถแยกวิเคราะห์ แสดงผลใน Swagger UI และสร้าง SDK ได้ แต่มันแค่ไม่สอดคล้องกัน และตัวตรวจสอบความถูกต้องทั่วไปก็ไม่มีอะไรจะพูดถึงเรื่องนี้
นั่นคือช่องว่างที่ linter เข้ามาเติมเต็ม ตัวตรวจสอบความถูกต้องจะตอบว่า “สเปกนี้เป็น OpenAPI ที่ถูกต้องตามกฎหมายหรือไม่” ส่วน linter จะตอบว่า “สเปกนี้เป็นไปตามกฎที่เราตกลงกันไว้หรือไม่” เครื่องมือโอเพนซอร์สที่ได้รับความนิยมมากที่สุดสำหรับคำถามที่สองคือ Spectral ซึ่งเป็น linter ของ Stoplight สำหรับเอกสาร JSON และ YAML มันมาพร้อมกับชุดกฎ OpenAPI ในตัว ช่วยให้คุณเขียนกฎของคุณเองได้ และสามารถรันได้จากเทอร์มินัลหรือจาก Editor ของคุณ หากคุณต้องการวิธีที่ฟรีและสามารถเขียนสคริปต์ได้เพื่อบังคับใช้ API style guide Spectral คือจุดเริ่มต้นที่ชัดเจน และคู่มือนี้จะแสดงวิธีการใช้งานอย่างถูกต้อง
นอกจากนี้ยังแสดงให้เห็นถึงข้อแลกเปลี่ยน Spectral คือชุดกฎที่คุณประกอบและบำรุงรักษา สำหรับทีมที่ต้องการการตรวจสอบความสอดคล้อง, mock server และการทดสอบที่ทำงานได้จากที่เดียว โดยไม่ต้องเขียนกฎ YAML ด้วยตนเอง Apidog ได้รวมงานเหล่านั้นเข้ากับส่วนติดต่อผู้ใช้งานการออกแบบเอง เราจะให้เครดิต Spectral อย่างเต็มที่ก่อน แล้วจึงแสดงให้เห็นว่าเส้นทางแบบ All-in-one ช่วยลดภาระการดูแลรักษาได้อย่างไร
Spectral ทำอะไรได้บ้าง
Spectral คือ linter ทั่วไป คุณสามารถชี้มันไปที่เอกสารที่มีโครงสร้าง กำหนดชุดกฎให้กับมัน แล้วมันจะรายงานทุกจุดที่เอกสารนั้นละเมิดกฎ พร้อมระบุหมายเลขบรรทัดและความรุนแรง มันไม่ได้จำเพาะเจาะจงกับ OpenAPI; แต่มันเข้าใจ OpenAPI, AsyncAPI และ Arazzo ได้ทันทีที่คุณใช้งาน และคุณสามารถ lint ไฟล์ JSON หรือ YAML ใดๆ ก็ได้ด้วยกฎที่คุณกำหนดเอง
เหตุผลที่มันสำคัญสำหรับงาน API คือชุดกฎ spectral:oas ที่มาพร้อมกับตัวมัน ชุดกฎนี้รวบรวมข้อกำหนดมาตรฐานของ OpenAPI ไว้มากมาย เช่น การทำงานควรมี operationId อ็อบเจกต์ info ควรมี description และ contact แท็กควรถูกกำหนดก่อนนำไปใช้ พารามิเตอร์ไม่ควรซ้ำกัน เมื่อคุณรันมันกับสเปกที่ใช้งานจริง คุณมักจะได้รับรายการคำเตือนในการลองครั้งแรกเสมอ ไม่มีข้อผิดพลาดใดที่ทำให้ parser เสียหาย แต่ทั้งหมดกลับทำให้สเปกใช้งานได้ยากขึ้น
นี่เป็นงานที่แตกต่างจากการตรวจสอบโครงสร้าง เครื่องมืออย่าง swagger-cli หรือ Redocly จะตอบว่าเอกสารเป็นไปตาม OpenAPI schema หรือไม่ ส่วน Spectral จะตอบว่าเอกสารเป็นไปตามรูปแบบที่คุณกำหนดไว้หรือไม่ คุณต้องการทั้งสองอย่าง และการตรวจสอบทั้งสองแบบนี้สามารถรวมกันใน pipeline ได้อย่างเรียบร้อย เราจะกล่าวถึงการตรวจสอบความถูกต้องในคู่มือเรื่อง วิธีการตรวจสอบ OpenAPI specs; ส่วนบทความนี้จะเกี่ยวกับเรื่องรูปแบบและความสอดคล้องกัน
การติดตั้ง Spectral และการรัน lint ครั้งแรกของคุณ
Spectral มาในรูปแบบ npm package CLI คือ @stoplight/spectral-cli ติดตั้งทั่วโลกด้วยคำสั่ง:
npm install -g @stoplight/spectral-cli
Node.js เป็นเพียง dependency เดียวของระบบ ดังนั้นเครื่องใดก็ตามหรือ CI image ที่ติดตั้ง Node ไว้แล้วก็สามารถรันได้ หากคุณไม่ต้องการติดตั้งแบบ global คุณสามารถใช้ npx @stoplight/spectral-cli ... ซึ่งทำงานได้บน ephemeral build runner
Spectral ต้องการ ruleset เพื่อทราบว่าจะตรวจสอบอะไร ตามธรรมเนียมแล้วไฟล์ดังกล่าวจะชื่อ .spectral.yaml ใน directory ที่คุณกำลังทำงานอยู่ ไฟล์ที่ใช้งานได้เล็กที่สุดจะขยายกฎ OpenAPI ที่มีมาในตัว:
# .spectral.yaml
extends: ["spectral:oas"]
ตอนนี้ lint สเปก ด้วยไฟล์ .spectral.yaml ที่อยู่ใน directory ปัจจุบัน Spectral จะตรวจจับมันได้โดยอัตโนมัติ:
spectral lint openapi.yaml
หรือระบุ ruleset โดยตรง:
spectral lint openapi.yaml --ruleset .spectral.yaml
ผลลัพธ์ที่ได้นั้นตั้งใจให้อ่านง่าย แต่ละสิ่งที่พบจะแสดงหมายเลขบรรทัดและคอลัมน์ ความรุนแรง กฎที่ถูกเรียกใช้ และข้อความที่เข้าใจง่ายสำหรับมนุษย์:
openapi.yaml
3:6 warning info-contact Info object should contain `contact` object.
5:10 error info-description OpenAPI object info `description` must be present.
✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)
การรันครั้งแรกกับสเปกที่มีอยู่เป็นช่วงเวลาที่ทีมส่วนใหญ่ตระหนักว่ามีการเบี่ยงเบนไปจากเดิมมากแค่ไหน กฎเหล่านั้นไม่เคยถูกบังคับใช้ ดังนั้นจึงไม่มีใครปฏิบัติตาม
การเขียนกฎของคุณเอง
ชุดกฎที่มีมาในตัวเป็นเพียงจุดเริ่มต้น ไม่ใช่ปลายทาง คุณค่าที่แท้จริงของ Spectral คือการนำข้อกำหนดของทีมคุณมาเข้ารหัสเป็นกฎที่เครื่องจักรจะตรวจสอบทุกครั้งที่มีการเปลี่ยนแปลง กฎหนึ่งข้อมีองค์ประกอบสี่ส่วน: จะดูอะไร (given, นิพจน์ JSONPath), จะตรวจสอบอะไร (then, ฟังก์ชัน), จะแสดงความรุนแรงแค่ไหน (severity) และจะพูดอะไรเมื่อล้มเหลว (message)
# .spectral.yaml
extends: ["spectral:oas"]
rules:
paths-kebab-case:
description: Paths should be kebab-case.
message: "{{property}} should be kebab-case (lower-case, hyphen-separated)"
severity: warn
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"
given จะเลือกคีย์พาธทั้งหมด then จะรันฟังก์ชัน pattern ที่มีมาในตัวโดยใช้ regular expression หากมีสิ่งใดที่ไม่ผ่าน pattern จะถูกรายงานเป็นคำเตือนพร้อมข้อความที่คุณกำหนด คุณสามารถห้ามใช้ Integer ID เพื่อสนับสนุน UUIDs, กำหนดให้มีการตอบสนองข้อผิดพลาดในทุกๆ POST, ห้ามใช้หมายเลขเวอร์ชันใน Server URL หรือกำหนดให้ทุก operation ต้องมี description Spectral มาพร้อมกับฟังก์ชันหลักหลายอย่าง (เช่น truthy, pattern, schema, length, enumeration และอื่นๆ) ดังนั้นข้อกำหนดส่วนใหญ่จึงไม่จำเป็นต้องใช้โค้ดเลย
เมื่อกฎต้องการตรรกะที่ฟังก์ชันไม่สามารถระบุได้ Spectral ช่วยให้คุณสามารถเขียนกฎใน JavaScript หรือ TypeScript และนำเข้าฟังก์ชันที่คุณสร้างขึ้นเองได้ นี่คือจุดที่เครื่องมือนี้มีประสิทธิภาพและเป็นจุดที่การบำรุงรักษาเริ่มต้นขึ้น หากคุณต้องการลงลึกในเรื่องนี้ เรามีคู่มือฉบับเต็มเกี่ยวกับการสร้าง กฎ Spectral แบบกำหนดเองด้วย TypeScript
ความรุนแรง และการทำให้ build ล้มเหลว
ทุกกฎของ Spectral มีระดับความรุนแรง: error, warn, info, หรือ hint โดยค่าเริ่มต้น CLI จะจบการทำงานด้วยโค้ดที่ไม่ใช่ศูนย์เมื่อพบ error เท่านั้น คำเตือนจะถูกพิมพ์ออกมาแต่ไม่ทำให้การรันล้มเหลว ซึ่งก็ใช้ได้ดีในขณะที่คุณกำลังแก้ไขสเปกเก่าและไม่ต้องการให้มีคำเตือนเป็นพันๆ รายการมาขัดขวางการรวมโค้ดทุกครั้ง
เมื่อสเปกของคุณสะอาดแล้ว ให้เพิ่มความเข้มงวด --fail-severity flag จะควบคุมระดับความรุนแรง:
spectral lint openapi.yaml --fail-severity=warn
ตอนนี้คำเตือนยังส่งคืน exit code 1 ซึ่งเป็นสิ่งที่ CI step อ่านเพื่อระบุว่าตัวเองล้มเหลว นี่คือกลไกที่เปลี่ยน linter ให้เป็น quality gate ที่แท้จริง: pipeline จะบล็อกการ merge ทันทีที่สเปกเริ่มเบี่ยงเบนไปจาก style guide คุณยังสามารถแทนที่ความรุนแรงของแต่ละกฎใน ruleset ของคุณได้ โดยการเพิ่มระดับกฎที่คุณสนใจจาก warn เป็น error หรือปิดใช้งานกฎที่ไม่เหมาะกับทีมของคุณโดยการตั้งค่าเป็น off
การรัน Spectral ใน CI
Linter ที่รันเฉพาะเมื่อมีคนจำได้ ไม่ใช่ gate จุดประสงค์คือการรันมันทุกครั้งที่มีการ push บนเครื่องที่สะอาด ด้วย ruleset เดียวกันสำหรับทุกคน Spectral ทำให้สิ่งนี้ง่ายขึ้น นี่คือ GitHub Actions job ที่จะ lint สเปกเมื่อมีการเปลี่ยนแปลงใน pull request ที่เกี่ยวข้อง:
name: Lint OpenAPI
on:
pull_request:
paths:
- "openapi.yaml"
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
- run: npm install -g @stoplight/spectral-cli
- run: spectral lint openapi.yaml --fail-severity=warn
สำหรับการรายงานที่ละเอียดขึ้น Spectral สามารถสร้าง JUnit XML ได้ ซึ่ง dashboard ของ CI ส่วนใหญ่จะแยกวิเคราะห์เป็น pass/fail tree:
spectral lint openapi.yaml -f junit -o results.xml
เชื่อมต่อ artifact นั้นเข้ากับ dashboard ของคุณ แล้วผู้ร่วมให้ข้อมูลทุกคนจะเห็นว่ากฎใดล้มเหลวและที่ใด โดยไม่ต้องอ่าน raw logs หากคุณต้องการภาพรวมที่กว้างขึ้นของการจัดชั้นการตรวจสอบโครงสร้าง, linting, และการตรวจจับการเปลี่ยนแปลงที่ทำให้เกิดการเสียหายร่วมกัน รูปแบบ OpenAPI-in-CI จะขยายขอบเขตเกินกว่าเครื่องมือเดียว การปฏิบัติกับสเปก เหมือนโค้ด เป็นแนวคิดที่ทำให้ทั้งหมดนี้เป็นไปได้
สิ่งที่ Spectral ต้องการจากคุณเป็นอย่างมาก
Spectral ทำงานได้ดีในสิ่งที่มันทำ ข้อจำกัดที่ตรงไปตรงมาคือมันทำเพียงอย่างเดียว และส่วนที่เหลือของวงจรชีวิตของสเปกเป็นปัญหาที่คุณต้องจัดการเอง ความจริงบางอย่างจะปรากฏขึ้นเมื่อทีมนำไปใช้จริงหลังจากที่ได้เห็นการสาธิตแล้ว
คุณเป็นเจ้าของ ruleset กฎ spectral:oas ที่มีมาในตัวเป็นแบบทั่วไป style guide ที่แท้จริงของคุณอยู่ในกฎที่คุณเขียนขึ้นเอง ตรวจสอบ กำหนดเวอร์ชัน และอัปเดตตามการเปลี่ยนแปลงของข้อกำหนดมาตรฐาน ruleset นั้นจะกลายเป็นโค้ดเบสขนาดเล็กที่มีภาระการบำรุงรักษาของตัวเอง และ JSONPath รวมถึงฟังก์ชันที่กำหนดเองเป็นทักษะที่ไม่ได้มีทุกคนในทีม
มัน lint เอกสาร ไม่ใช่ API Spectral อ่านไฟล์ มันไม่สามารถบอกคุณได้ว่าบริการที่กำลังทำงานอยู่ส่งคืนสิ่งที่สเปกสัญญาไว้จริงหรือไม่ สเปกอาจผ่านกฎ lint ทุกข้อแต่ยังคงอธิบายถึงเอนด์พอยต์ที่การใช้งานจริงเบี่ยงเบนไปแล้วเมื่อหลายเดือนก่อน การแก้ไขช่องว่างนี้หมายถึงการส่งคำขอจริงและยืนยันการตอบกลับ ซึ่งเป็นเครื่องมือที่แตกต่างออกไปโดยสิ้นเชิง
มันเป็นส่วนหนึ่งของห่วงโซ่ที่ยาวขึ้น หลังจากการ lint คุณยังคงต้องการ mock สำหรับทีม frontend, เว็บไซต์เอกสารประกอบ และชุดทดสอบอัตโนมัติ แต่ละส่วนเป็นเครื่องมือที่แยกต่างหากที่ต้องติดตั้ง กำหนดค่า และรักษาให้สอดคล้องกับสเปก Linter ไม่ทราบเกี่ยวกับสิ่งเหล่านี้เลย ดังนั้นสเปกจะถูกแยกวิเคราะห์และตีความใหม่ในทุกขั้นตอน
ทั้งหมดนี้ไม่ใช่การโจมตี Spectral มันเป็น linter ที่มุ่งเน้นและซื่อสัตย์ต่อขอบเขตของมัน แต่คำว่า "มุ่งเน้น" หมายความว่างานด้านการบูรณาการจะตกอยู่กับคุณ
วิธีที่ง่ายกว่า: ความสอดคล้องที่สร้างขึ้นในส่วนติดต่อผู้ใช้งานการออกแบบ
นี่คืออีกทางเลือกหนึ่ง แทนที่จะมองว่าความสอดคล้องเป็นขั้นตอนการ lint ที่เพิ่มเข้ามาหลังจากเขียนสเปกแล้ว Apidog มองว่ามันเป็นส่วนหนึ่งของการเขียนสเปกเลยทีเดียว
Apidog เป็นแพลตฟอร์ม API แบบ All-in-one: คุณออกแบบ schema, ดีบักคำขอ, สร้าง test scenario, mock endpoint และเผยแพร่เอกสารใน workspace เดียวกัน เนื่องจากการออกแบบเกิดขึ้นภายในเครื่องมือ การตรวจสอบความสอดคล้องจึงเกิดขึ้นในขณะที่คุณพิมพ์ ตัวออกแบบภาพจะแสดงปัญหาโครงสร้างทันทีที่ปรากฏ เหมือนกับคอมไพเลอร์ที่ขีดเส้นใต้ข้อผิดพลาดทางไวยากรณ์ ดังนั้นคุณจึงแก้ไขได้ก่อนที่จะมีการ commit คุณไม่จำเป็นต้องรัน linter แยกต่างหากหลังจากนั้น; editor นั่นแหละคือ linter
ความแตกต่างที่ใหญ่กว่าคือทุกอย่างที่ตามมา สัญญาที่คุณออกแบบจะกลายเป็น mock server, เอกสารเชิงโต้ตอบ และ test scenario ของคุณ โดยไม่ต้องมีการแยกวิเคราะห์ซ้ำ และไม่ต้องใช้เครื่องมือที่สองในการรักษาความสอดคล้อง เมื่อคุณต้องการการตรวจสอบเหล่านั้นใน pipeline Apidog CLI จะรัน test scenario ของคุณแบบ headless จากเทอร์มินัลและจบการทำงานด้วยโค้ดที่ไม่ใช่ศูนย์เมื่อล้มเหลว ซึ่งเป็นพฤติกรรมการเป็น gate ที่คุณต้องการจาก linter ยกเว้นว่ามันจะทดสอบ API ที่กำลังทำงานอยู่เทียบกับสัญญา แทนที่จะอ่านแค่ไฟล์ ติดตั้งด้วยคำสั่ง npm เดียวแล้วชี้ไปที่ scenario:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli
นั่นเติมเต็มช่องว่างที่ Spectral เปิดทิ้งไว้ Spectral ยืนยันว่าเอกสารเป็นไปตามรูปแบบของคุณ Apidog CLI ยืนยันว่าการใช้งานจริงยังคงตรงกับเอกสาร สำหรับการอ้างอิง flag แบบเต็ม ให้รัน apidog run --help หรืออ่าน คู่มือ CLI ฉบับสมบูรณ์
ดังนั้นข้อแลกเปลี่ยนนี้จึงเป็นของจริงและควรระบุให้ชัดเจน Spectral ให้ linter ที่ฟรี, สามารถเขียนสคริปต์ได้, และไม่ขึ้นกับผู้ขาย ซึ่งคุณสามารถประกอบและบำรุงรักษาเองได้ Apidog ให้ความสอดคล้อง, การจำลอง, เอกสารประกอบ และการทดสอบที่รันได้จากแหล่งข้อมูลเดียว โดยมีการเชื่อมโยงกันน้อยกว่ามาก หากขั้นตอนการ lint ที่พกพาได้ใน toolchain ที่มีอยู่เป็นสิ่งที่คุณต้องการ Spectral เป็นคำตอบที่ดี แต่ถ้าคุณต้องการให้วงจรชีวิตทั้งหมดคงอยู่ได้โดยไม่กลายเป็นโครงการเครื่องมือแยกต่างหาก เส้นทางที่รวมเข้าด้วยกันจะช่วยประหยัดค่าใช้จ่ายของคุณในระยะยาว
Spectral vs Apidog โดยสรุป
| ความสามารถ | Spectral | Apidog |
|---|---|---|
| การตรวจสอบรูปแบบ OpenAPI (linting) | มี, ผ่าน spectral:oas + กฎที่กำหนดเอง |
มี, แสดงผลแบบเรียลไทม์ในดีไซเนอร์ |
| กฎที่กำหนดเอง | มี, YAML หรือ JS/TS, คุณต้องบำรุงรักษาเอง | ข้อกำหนดถูกบังคับใช้โดย editor, ไม่ต้องเขียนโค้ดกฎ |
| การตรวจสอบโครงสร้าง | ร่วมกับ Redocly หรือตัวตรวจสอบอื่น | มีมาในตัวตั้งแต่ขั้นตอนการออกแบบ |
| Mock server | ไม่มี | มี |
| เอกสารที่สร้างอัตโนมัติ | ไม่มี | มี |
| การทดสอบ API ที่รันได้ | ไม่มี | มี, ผ่าน Apidog CLI |
| CI gate | spectral lint --fail-severity=warn |
apidog run จบการทำงานด้วยโค้ดที่ไม่ใช่ศูนย์ |
| ค่าใช้จ่าย | ฟรี, โอเพนซอร์ส | มีแบบฟรี (Free tier), มีแผนบริการแบบชำระเงิน |
ใช้ตารางนี้เป็นตัวช่วยในการตัดสินใจ ไม่ใช่การจัดอันดับ ทางเลือกที่เหมาะสมคือทางเลือกที่ตรงกับปริมาณของวงจรชีวิตที่คุณต้องการให้เครื่องมือเดียวจัดการ
คำถามที่พบบ่อย
Spectral ฟรีหรือไม่? ใช่ Spectral เป็นโอเพนซอร์สภายใต้ใบอนุญาต Apache 2.0 โดย Stoplight เป็นผู้ดูแล CLI, ชุดกฎ OpenAPI ที่มีมาในตัว และการสร้างกฎแบบกำหนดเอง ล้วนใช้งานได้ฟรี
Spectral ตรวจสอบความถูกต้องว่าสเปกของฉันเป็น OpenAPI ที่ถูกต้องตามกฎหมายหรือไม่? บางส่วน กฎที่มาพร้อมกับตัวมันสามารถตรวจจับปัญหาโครงสร้างได้หลายอย่าง แต่ Spectral เป็น linter ไม่ใช่ตัวตรวจสอบ schema โดยเฉพาะ ควรใช้คู่กับตัวตรวจสอบความถูกต้องเพื่อความครอบคลุมโครงสร้างทั้งหมด คู่มือเรื่อง การตรวจสอบ OpenAPI specs ครอบคลุมด้านนั้น และ เครื่องมือตรวจสอบ OpenAPI ที่ดีที่สุด เปรียบเทียบทางเลือกต่างๆ
Spectral สามารถทดสอบ API ที่กำลังทำงานของฉันได้หรือไม่? ไม่ได้ Spectral อ่านเฉพาะไฟล์สเปกเท่านั้น หากต้องการตรวจสอบว่า API ที่ใช้งานจริงตรงกับสัญญา คุณต้องมี runner ที่ส่งคำขอจริงและยืนยันการตอบกลับ เช่น Apidog CLI
ฉันจะทำให้คำเตือนของ Spectral ทำให้ CI build ของฉันล้มเหลวได้อย่างไร? รัน spectral lint openapi.yaml --fail-severity=warn โดยค่าเริ่มต้น เฉพาะความรุนแรงระดับ error เท่านั้นที่จะทำให้ build ล้มเหลว; --fail-severity=warn จะทำให้คำเตือนส่งคืน exit code ที่ไม่ใช่ศูนย์ด้วย
Spectral และ Apidog แตกต่างกันอย่างไร? Spectral เป็น linter แบบโอเพนซอร์สที่เน้นการทำงานเฉพาะด้านที่คุณต้องกำหนดค่าและบำรุงรักษาเอง ส่วน Apidog เป็นแพลตฟอร์มแบบ all-in-one ที่รวมการออกแบบ การตรวจสอบความสอดคล้อง การจำลอง เอกสารประกอบ และการทดสอบไว้ด้วยกัน คุณจึงประกอบและรักษาความสอดคล้องน้อยลง ดู Apidog vs Swagger สำหรับการเปรียบเทียบที่เกี่ยวข้องในภาพรวมของเครื่องมือออกแบบ
สรุป
Spectral แก้ปัญหาจริงที่ตัวตรวจสอบความถูกต้องแบบง่ายมองข้ามไป: การรักษาสเปก OpenAPI ให้สอดคล้องกับข้อกำหนดมาตรฐานที่ทีมของคุณตกลงกันไว้ ติดตั้ง @stoplight/spectral-cli ขยาย spectral:oas เพิ่มกฎที่กำหนดเองไม่กี่ข้อ และสร้าง gate ให้ pipeline ของคุณด้วย --fail-severity=warn สำหรับหลายๆ ทีม สิ่งนี้ก็เพียงพอแล้วและไม่มีค่าใช้จ่ายใดๆ
ค่าใช้จ่ายจะปรากฏขึ้นในภายหลัง ในกฎที่คุณบำรุงรักษาและส่วนที่เหลือของวงจรชีวิตที่คุณต้องเชื่อมโยงเข้ากับ linter หากคุณต้องการความสอดคล้อง, mocks, docs และการทดสอบที่รันได้จากแหล่งข้อมูลเดียว ดาวน์โหลด Apidog และสร้างสเปกของคุณในที่ที่การตรวจสอบเป็นส่วนหนึ่งของพื้นผิวการทำงานอยู่แล้ว ไม่ว่าจะเลือกทางใด เป้าหมายก็เหมือนกัน: สเปกที่ทั้งทีมของคุณสามารถเชื่อถือได้ ซึ่งถูกบังคับใช้โดยเครื่องจักรแทนที่จะเป็นความหวัง