swagger editor

⏰️ กำลังมองหา Swagger Editor เวอร์ชันถัดไปอยู่หรือเปล่า?

SwaggerEditor ได้รับการเผยแพร่ภายใต้สองช่องทางการเผยแพร่หลัก:

1. SwaggerEditor@4 - เปิดตัวจากสาขาหลักและปรับใช้ที่ https://editor.swagger.io/
2. SwaggerEditor@5 - เปิดตัวจากสาขาถัดไปและปรับใช้ที่ https://editor-next.swagger.io/

มีเพียง SwaggerEditor@5 เท่านั้นที่รองรับ OpenAPI 3.1.0 SwaggerEditor@4 จะไม่ได้รับการสนับสนุน OpenAPI 3.1.0 และถือเป็นเวอร์ชันดั้งเดิม ณ จุดนี้ แผนคือการโยกย้ายอย่างสมบูรณ์ไปยัง SwaggerEditor@5 อย่างต่อเนื่อง และเลิกใช้งาน SwaggerEditor@4 ในอนาคต

---

️ กำลังมองหา Swagger Editor เวอร์ชันเก่าอยู่หรือเปล่า? อ้างถึงสาขา 2.x หรือ 3.x

---

Swagger Editor ช่วยให้คุณแก้ไข คำจำกัดความของ OpenAPI API (OpenAPI 2.0 และ OpenAPI 3.0.3) ในรูปแบบ JSON หรือ YAML ภายในเบราว์เซอร์ของคุณ และเพื่อดูตัวอย่างเอกสารประกอบแบบเรียลไทม์ จากนั้นจึงสามารถสร้างคำจำกัดความของ OpenAPI ที่ถูกต้องและใช้กับเครื่องมือ Swagger เต็มรูปแบบได้ (การสร้างโค้ด เอกสารประกอบ ฯลฯ)

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

พื้นที่เก็บข้อมูลนี้เผยแพร่ไปยังโมดูล NPM สองโมดูลที่แตกต่างกัน:

• Swagger-editor เป็นโมดูล npm แบบดั้งเดิมที่มีไว้สำหรับใช้ในแอปพลิเคชันหน้าเดียวที่สามารถแก้ไขการขึ้นต่อกัน (ผ่าน Webpack, Browserify ฯลฯ )
• swagger-editor-dist เป็นโมดูลที่ไม่มีการพึ่งพาซึ่งมีทุกสิ่งที่คุณต้องการเพื่อให้บริการ Swagger Editor ในโปรเจ็กต์ฝั่งเซิร์ฟเวอร์ หรือโปรเจ็กต์เว็บที่ไม่สามารถแก้ไขการขึ้นต่อกันของโมดูล npm

หากคุณกำลังสร้างแอปพลิเคชันหน้าเดียว ขอแนะนำให้ใช้ swagger-editor เนื่องจาก swagger-editor-dist มีขนาดใหญ่กว่ามาก

การวิเคราะห์ที่ไม่ระบุชื่อ

Swagger Editor ใช้ Scarf เพื่อรวบรวมการวิเคราะห์การติดตั้งที่ไม่ระบุชื่อ การวิเคราะห์เหล่านี้ช่วยสนับสนุนผู้ดูแลไลบรารีนี้และทำงานเฉพาะระหว่างการติดตั้งเท่านั้น หากต้องการยกเลิก คุณสามารถตั้งค่าฟิลด์ scarfSettings.enabled เป็น false ใน package.json ของโปรเจ็กต์ของคุณได้ :

 // package.json
{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

หรือคุณสามารถตั้งค่าตัวแปรสภาพแวดล้อม SCARF_ANALYTICS เป็น false โดยเป็นส่วนหนึ่งของสภาพแวดล้อมที่ติดตั้งแพ็คเกจ npm ของคุณ เช่น SCARF_ANALYTICS=false npm install

สคริปต์ที่เป็นประโยชน์

สคริปต์ใดๆ ด้านล่างนี้สามารถเรียกใช้ได้โดยการพิมพ์ npm run <script name> ในไดเร็กทอรีรากของโปรเจ็กต์

กำลังพัฒนา

ชื่อสคริปต์	คำอธิบาย
dev	วางไข่เซิร์ฟเวอร์ dev แบบ hot-reloading บนพอร์ต 3200
deps-check	สร้างรายงานขนาดและใบอนุญาตเกี่ยวกับการพึ่งพาของ Swagger Editor
lint	รายงานข้อผิดพลาดและคำเตือนเกี่ยวกับสไตล์ ESLint
lint-errors	รายงานข้อผิดพลาดสไตล์ ESLint โดยไม่มีคำเตือน
lint-fix	พยายามแก้ไขข้อผิดพลาดของสไตล์โดยอัตโนมัติ
watch	สร้างไฟล์หลักใหม่ใน /dist เมื่อซอร์สโค้ดเปลี่ยนแปลง มีประโยชน์สำหรับ npm link

อาคาร

ชื่อสคริปต์	คำอธิบาย
build	สร้างชุดเนื้อหา JS และ CSS ใหม่และส่งออกไปที่ /dist
build:bundle	สร้าง swagger-editor-bundle.js เท่านั้น (commonJS)
build:core	สร้าง swagger-editor.(js|css) เท่านั้น (commonJS)
build:standalone	สร้าง swagger-editor-standalone-preset.js เท่านั้น (commonJS)
build:stylesheets	สร้าง swagger-editor.css เท่านั้น
build:es:bundle	สร้าง swagger-editor-es-bundle.js เท่านั้น (es2015)
build:es:bundle:core	สร้าง swagger-editor-es-bundle-core.js เท่านั้น (es2015)

การทดสอบ

ชื่อสคริปต์	คำอธิบาย
test	รันการทดสอบหน่วยใน Node รันการทดสอบ Cypress end-to-end และรัน ESLint ในโหมดเฉพาะข้อผิดพลาด
test:unit-mocha	รันการทดสอบหน่วยที่ใช้ Mocha ใน Node.
test:unit-jest	รันการทดสอบหน่วยตาม Jest ใน Node.
e2e	รันการทดสอบเบราว์เซอร์แบบ end-to-end ด้วย Cypress
lint	รันการทดสอบ ESLint
test:artifact	รันรายการการทดสอบสิ่งประดิษฐ์บันเดิลใน Jest
test:artifact:umd:bundle	เรียกใช้การทดสอบหน่วยที่ยืนยันการส่งออกกลุ่ม swagger-editor-bundle เป็นฟังก์ชัน
test:artifact:es:bundle	เรียกใช้การทดสอบหน่วยที่ยืนยันการส่งออกแบบ swagger-editor-es-bundle เป็นฟังก์ชัน
test:artifact:es:bundle:core	เรียกใช้การทดสอบหน่วยที่ยืนยันการส่งออกแบบ swagger-editor-es-bundle-core เป็นฟังก์ชัน

ดำเนินการในพื้นที่

ข้อกำหนดเบื้องต้น

• git เวอร์ชันใดก็ได้
• Node.js >=20.3.0 และ npm >=9.6.7 เป็นเวอร์ชันขั้นต่ำที่จำเป็นที่ repo นี้ทำงาน แต่เราแนะนำให้ใช้ Node.js เวอร์ชันล่าสุดเสมอ

 $ npm i --legacy-peer-deps

หากคุณติดตั้ง Node.js และ npm คุณสามารถเรียกใช้ npm start เพื่อหมุนเซิร์ฟเวอร์แบบคงที่ได้

มิฉะนั้น คุณสามารถเปิด index.html ได้โดยตรงจากระบบไฟล์ในเบราว์เซอร์ของคุณ

หากคุณต้องการเปลี่ยนแปลงโค้ดเป็น Swagger Editor คุณสามารถเริ่มต้นเซิร์ฟเวอร์ dev แบบ hot-reloading ของ Webpack ผ่านทาง npm run dev

รองรับเบราว์เซอร์

Swagger Editor ทำงานได้ใน Chrome, Safari, Firefox และ Edge เวอร์ชันล่าสุด

ปัญหาที่ทราบ

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

• ทุกอย่างอยู่ในรายการปัญหาที่ทราบของ Swagger UI
• การบูรณาการกับโคเดเจนยังคงขาดหายไป

นักเทียบท่า

เรียกใช้ภาพจาก DockerHub

มีรูปภาพนักเทียบท่าที่เผยแพร่ใน DockerHub

เมื่อต้องการใช้สิ่งนี้ ให้รันสิ่งต่อไปนี้:

 docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

สิ่งนี้จะเรียกใช้ Swagger Editor (ในโหมดเดี่ยว) บนพอร์ต 80 บนเครื่องของคุณ ดังนั้นคุณจึงสามารถเปิดได้โดยไปที่ http://localhost ในเบราว์เซอร์ของคุณ

• คุณสามารถระบุ URL ที่ชี้ไปยังคำจำกัดความของ API ได้ (อาจไม่สามารถใช้ได้หากบังคับใช้นโยบายความปลอดภัยบางอย่าง เช่น CSP หรือ CORS)

 docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor

• คุณสามารถจัดเตรียมไฟล์คำจำกัดความ json หรือ yaml ของคุณเองได้จากโฮสต์ภายในเครื่องของคุณ:

 docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor

หมายเหตุ: เมื่อตั้งค่าตัวแปรสภาพแวดล้อมทั้ง URL และ SWAGGER_FILE แล้ว URL จะมีลำดับความสำคัญและ SWAGGER_FILE จะถูกละเว้น

• คุณสามารถระบุ URL ฐานอื่นผ่านตัวแปร BASE_URL เพื่อเข้าถึงแอปพลิเคชัน - ตัวอย่างเช่น หากคุณต้องการให้แอปพลิเคชันพร้อมใช้งานที่ http://localhost/swagger-editor/ :

 docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor

• คุณสามารถระบุพอร์ตอื่นผ่านตัวแปร PORT เพื่อเข้าถึงแอปพลิเคชัน ค่าเริ่มต้นคือ 8080

 docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor

• คุณสามารถระบุรหัส Google Tag Manager ผ่านตัวแปร GTM เพื่อติดตามการใช้งานของตัวแก้ไขผยอง

 docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor

คุณยังสามารถปรับแต่งตำแหน่งข้อมูลต่างๆ ที่ใช้โดย Swagger Editor ด้วยตัวแปรสภาพแวดล้อมต่อไปนี้ ตัวอย่างเช่น สิ่งนี้อาจมีประโยชน์หากคุณมีเซิร์ฟเวอร์ตัวสร้าง Swagger ของคุณเอง:

ตัวแปรสภาพแวดล้อม	ค่าเริ่มต้น
URL_SWAGGER2_GENERATOR	https://generator.swagger.io/api/swagger.json
URL_OAS3_GENERATOR	https://generator3.swagger.io/openapi.json
URL_SWAGGER2_CONVERTER	https://converter.swagger.io/api/convert

หากคุณต้องการเรียกใช้ Swagger Editor ในเครื่องโดยไม่มีคุณสมบัติ Codegen (สร้างเซิร์ฟเวอร์และสร้างไคลเอนต์) คุณสามารถตั้งค่าตัวแปรสภาพแวดล้อมด้านบนเป็น null ( URL_SWAGGER2_CONVERTER=null )

การสร้างและเรียกใช้อิมเมจในเครื่อง

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

 # Install npm packages (if needed)
npm install

# Build the app
npm run build

# Build an image
docker build -t swagger-editor .

# Run the container
docker run -d -p 80:8080 swagger-editor

จากนั้นคุณสามารถดูแอปได้โดยไปที่ http://localhost ในเบราว์เซอร์ของคุณ

เอกสารประกอบ

• กำลังนำเข้าเอกสาร OpenAPI ของคุณ

• มีส่วนร่วม

ใช้ React เวอร์ชันเก่า

สำคัญ

โดยเวอร์ชันเก่าเราอ้างถึง React >=17 <18 โดยเฉพาะ

ตามค่าเริ่มต้น แพ็คเกจ swagger-editor@4 npm จะมาพร้อมกับ React@18 เวอร์ชันล่าสุด คุณสามารถใช้แพ็คเกจ swagger-editor@4 npm กับ React เวอร์ชันเก่าได้

สมมติว่าแอปพลิเคชันของฉันทำงานร่วมกับแพ็คเกจ swagger-editor@4 npm และใช้ [email protected]

เวลา 22.00 น

เพื่อแจ้งแพ็คเกจ swagger-editor@4 npm ว่าฉันต้องการให้ใช้เวอร์ชัน React ฉันจำเป็นต้องใช้การแทนที่ npm

{
  "dependencies" : {
    "react" : " =17.0.2 " ,
    "react-dom" : " =17.0.2 "
  },
  "overrides" : {
    "swagger-editor" : {
      "react" : " $react " ,
      "react" : " $react-dom " ,
      "react-redux" : " ^8 "
    }
  }
}

บันทึก

การแทนที่ React และ ReactDOM ถูกกำหนดให้เป็นการอ้างอิงถึงการขึ้นต่อกัน เนื่องจาก react-redux@9 รองรับเฉพาะ React >= 18 เราจึงจำเป็นต้องใช้ react-redux@8

เส้นด้าย

เพื่อแจ้งแพ็คเกจ swagger-editor@4 npm ว่าฉันต้องการให้ใช้เวอร์ชัน React เฉพาะของฉัน ฉันจำเป็นต้องใช้ความละเอียดเส้นด้าย

{
  "dependencies" : {
    "react" : " 17.0.2 " ,
    "react-dom" : " 17.0.2 "
  },
  "resolutions" : {
    "swagger-editor/react" : " 17.0.2 " ,
    "swagger-editor/react-dom" : " 17.0.2 " ,
    "swagger-editor/react-redux" : " ^8 "
  }
}

บันทึก

ความละเอียด React และ ReactDOM ไม่สามารถกำหนดเป็นการอ้างอิงถึงการขึ้นต่อกัน น่าเสียดายที่ เส้นด้าย ไม่รองรับนามแฝงเช่น $react หรือ $react-dom เหมือนที่ npm ทำ คุณจะต้องระบุเวอร์ชันที่แน่นอน

ติดต่อฝ่ายรักษาความปลอดภัย

โปรดเปิดเผยปัญหาหรือช่องโหว่ด้านความปลอดภัยโดยส่งอีเมลไปที่ [email protected] แทนที่จะใช้เครื่องมือติดตามปัญหาสาธารณะ