หน้านี้มีรายละเอียดโครงการงานเขียนเชิงเทคนิคที่ได้รับการยอมรับใน Google Season of เอกสาร
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- Cloud Native Computing Foundation (CNCF)
- นักเขียนเชิงเทคนิค:
- feloy
- ชื่อโปรเจ็กต์:
- อัปเดตวิธีที่เว็บไซต์ Kubernetes แสดงข้อมูลอ้างอิง API
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ปัจจุบันข้อมูลอ้างอิง Kubernetes API เป็นเอกสาร HTML ขนาดใหญ่ที่สร้างขึ้นจากข้อกำหนดของ Swagger โดยสคริปต์ที่โฮสต์นอกที่เก็บเว็บไซต์ จากนั้นจึงเพิ่มลงในที่เก็บเว็บไซต์นี้
ในทางกลับกัน เว็บไซต์เอกสารประกอบของ Kubernetes สร้างขึ้นด้วย Hugo จากเอกสารประกอบที่เขียนในรูปแบบ Markdown ในที่เก็บข้อมูลเว็บไซต์ โดยใช้ธีม Docsy Hugo
เป้าหมายของโปรเจ็กต์นี้คือผสานรวมการสร้างข้อมูลอ้างอิง Kubernetes API เข้ากับกระบวนการสร้างเว็บไซต์เอกสารประกอบ
โดยเฉพาะอย่างยิ่ง เราจะมุ่งเน้นที่ shortcode ของ swaggerui ซึ่งเป็น Wrapper ของ swagger-ui ที่ธีม Docsy Hugo ให้มา และเครื่องมือเฉพาะ ซึ่งช่วยให้แทรกข้อกำหนดบางส่วนของ API ลงในลำดับของเอกสารประกอบ Kubernetes ได้
จำเป็นต้องใช้เครื่องมือที่เฉพาะเจาะจงเนื่องจาก swagger-ui สามารถแสดงข้อกำหนดที่สมบูรณ์ที่อธิบายไว้ในไฟล์ swagger แต่ไม่สามารถแสดงส่วนต่างๆ ของไฟล์ (ดู 8) Kubernetes API มีขนาดใหญ่เกินกว่าที่จะแสดงในเพียงส่วนเดียว (ตัวอย่างเอาต์พุต) เราจะพิจารณา 2 แนวทาง ดังนี้
แนวทางแรกคือสร้างไฟล์ swagger หลายไฟล์ โดยสร้าง 1 ไฟล์สำหรับกลุ่ม Kubernetes API แต่ละกลุ่ม (core/v1, apps/v1, ...) จากแหล่งที่มาที่มีอยู่ใน (10) และใช้ไฟล์เหล่านี้เป็นอินพุตของรหัสการจัดเรียง swaggerui ในตำแหน่งที่เฉพาะเจาะจงในเว็บไซต์เอกสารประกอบของ Kubernetes
วิธีที่สองคือการสร้างเครื่องมือที่จะรับเป็นไฟล์ swagger ที่สมบูรณ์ของ Kubernetes API ซึ่งอยู่ที่ (11) และส่งออกไฟล์ swaggerui ใหม่สำหรับปลายทางที่ระบุหรือปลายทางจำนวนจำกัด รวมถึงทรัพยากรที่เกี่ยวข้องและคำอธิบาย จากนั้นใช้ไฟล์ swaggerui เหล่านี้เป็นอินพุตของ swaggerui ในตำแหน่งที่เจาะจงในเว็บไซต์เอกสารประกอบของ Kubernetes
เนื่องจากแหล่งที่มาของข้อกำหนด (10 และ 11) อยู่ในที่เก็บข้อมูลอื่นนอกเหนือจากแหล่งที่มาของเอกสารประกอบ เราจึงต้องหาวิธีอัปเดตข้อกำหนดเหล่านั้นในที่เก็บเอกสารประกอบโดยอัตโนมัติเมื่อมีการเปลี่ยนแปลง
เนื่องจากเอกสารประกอบของ Kubernetes มีให้บริการในภาษาต่างๆ เราจะให้ความสำคัญเป็นพิเศษกับโอกาสในการเผยแพร่คำแปลสำหรับข้อมูลอ้างอิง Kubernetes API