สร้างไฟล์ Swagger

ภาพรวม

เช่นที่เรารู้กัน, กรอบการทำงาน beego ให้การสนับสนุนในการสร้างไฟล์ swagger เพื่อชี้แจง API ผ่านเครื่องมือบรรทัดคำสั่งที่เรียกว่า "bee". Casdoor ก็ถูกสร้างขึ้นบนพื้นฐานของ beego เช่นกัน. อย่างไรก็ตาม, เราพบว่าไฟล์ swagger ที่สร้างโดย bee ไม่สามารถจัดหมวดหมู่ API ด้วยป้ายกำกับ "@Tag". ดังนั้น, เราได้แก้ไข bee ต้นฉบับเพื่อใช้งานฟังก์ชันนี้.

วิธีการเขียนคอมเมนต์

กฎส่วนใหญ่เหมือนกับรูปแบบคอมเมนต์ของ bee ต้นฉบับอย่างเป๊ะ. ความแตกต่างเพียงอย่างเดียวคือ API ควรจะถูกแบ่งออกเป็นกลุ่มต่างๆ ตามป้ายกำกับ "@Tag". ดังนั้น, นักพัฒนาจึงมีหน้าที่ต้องแน่ใจว่าป้ายกำกับนี้ถูกเพิ่มอย่างถูกต้อง. นี่คือตัวอย่าง:

// @Title Login
// @Tag Login API
// @Description login
// @Param   oAuthParams     query    string  true        "oAuth parameters"
// @Param   body    body   RequestForm  true        "Login information"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @router /login [post]
func (c *ApiController) Login() {

API ที่มีป้ายกำกับ "@Tag" เดียวกันจะถูกจัดใส่ในกลุ่มเดียวกัน.

วิธีการสร้างไฟล์ swagger

0. เขียนคอมเมนต์สำหรับ API ในรูปแบบที่ถูกต้อง.

1. ดึง repository นี้: https://github.com/casbin/bee.

2. สร้าง bee ที่ได้รับการแก้ไข. ตัวอย่างเช่น, ในไดเรกทอรีรากของ casbin/bee, รันคำสั่งต่อไปนี้:

   go build -o mybee .

3. คัดลอก mybee ไปยังไดเรกทอรีพื้นฐานของ casdoor.

4. ในไดเรกทอรีนั้น, รันคำสั่งต่อไปนี้:

   mybee generate docs

5. (ไม่จำเป็น) ถ้าคุณต้องการสร้างเอกสาร swagger สำหรับป้ายกำกับหรือ apis ที่เฉพาะเจาะจง, นี่คือบางคำสั่งตัวอย่าง:

   mybee generate docs --tags "Adapter API"
   mybee generate docs --tags "Adapter API,Login API"
   mybee generate docs --apis "add-adapter"
   mybee generate docs --apis "add-adapter,delete-adapter"

   โดยเฉพาะ: เราเพียงรับเครื่องหมายจุลภาค , เป็นตัวคั่นเมื่อมีการให้ป้ายกำกับหรือ apis หลายอัน.

จากนั้นคุณจะพบว่าไฟล์ swagger ใหม่ถูกสร้างขึ้น.