Gunakan Swagger untuk menjana dokumen API secara automatik dalam Beego

Gunakan Swagger dalam Beego untuk menjana dokumen API secara automatik

Apabila teknologi Internet menjadi semakin matang, semakin banyak syarikat mula mengubah model perniagaan mereka secara digital, dan API merupakan bahagian penting dalam transformasi digital menjadi semakin penting. Apabila membangunkan API, selain memastikan keselamatan dan kebolehpercayaan API, cara untuk membolehkan jurutera pembangunan bahagian hadapan dan belakang yang lain memahami dengan cepat dan menggunakan API yang mereka bangunkan juga merupakan bahagian yang sangat penting. Artikel ini akan memperkenalkan cara menggunakan alat Swagger untuk menjana dokumen API secara automatik apabila membangunkan API menggunakan rangka kerja Beego untuk memudahkan panggilan dan penggunaan jurutera pembangunan lain.

Apakah Swagger?

Swagger ialah spesifikasi API sumber terbuka dan set alat yang bertujuan untuk memudahkan dan menyeragamkan pembangunan dan penggunaan API. Ia boleh menjana antara muka interaktif secara automatik antara pembangun, pengguna dan dokumen, serta menyediakan banyak fungsi dokumen bantuan visual.

Mengapa menggunakan Swagger?

Sesetengah API memerlukan dokumentasi dan penerangan untuk membantu memahami penggunaannya dan cara memanggilnya Menggunakan Swagger boleh memudahkan dan menjana dokumen ini secara automatik. Menggunakan alat Swagger boleh menjadikan dokumen API lebih cantik, piawai dan mudah dibaca apabila dijana. Format mandatori Swagger juga boleh membantu pembangun dalam mereka bentuk dan melaksanakan API yang mematuhi spesifikasi piawai, sekali gus menjimatkan masa dan tenaga.

Menggunakan Swagger dalam Beego

1. Tambah kebergantungan

Untuk menggunakan Swagger dalam projek Beego, anda perlu menambah kebergantungan pustaka Swagger pada projek dulu. Anda boleh memasangnya melalui arahan berikut:

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

2. Edit ulasan Swagger

Dalam rangka kerja Beego, kami menggunakan ulasan dalam kod Penghala untuk menerangkan parameter dan permintaan API. Taip, nilai pulangan dan maklumat lain Apabila menggunakan Swagger, anda perlu menambah tag spesifikasi Swagger pada ulasan ini untuk menjana dokumen API secara automatik.

Berikut ialah contoh mudah:

// @Summary  获取一个用户信息
// @Description 通过ID获取一个用户信息
// @Accept  json
// @Produce  json
// @Param   id     path    int     true        "用户ID"
// @Success 200 {object} models.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

Dalam ulasan, kami menambahkan beberapa teg spesifikasi khas:

• @Ringkasan: Gambaran keseluruhan kaedah API
• @Description: Penerangan terperinci kaedah API
• @Accept: Accepted Content-Type type
• @Produce: Response Content-Type type
• @ Param: Permintaan parameter , termasuk nama parameter, lokasi, jenis data, sama ada ia diperlukan dan perihalan.
• @Success: Kod status HTTP dan jenis nilai pulangan bagi respons yang berjaya, yang juga boleh termasuk tatasusunan, struktur dan maklumat lain.
• @Router: Minta laluan dan kaedah permintaan.

Anda boleh menambah lebih banyak teg untuk menambah penerangan API seperti yang diperlukan.

3. Jana dokumentasi secara automatik

Selepas kami menambah ulasan spesifikasi Swagger pada kod, jalankan arahan berikut dalam direktori akar projek untuk menjana dokumentasi API:

swag init

Arahan ini akan menjana folder dokumen dalam direktori projek, yang akan mengandungi dokumentasi API yang dijana dan fail sumber statik.

4. Gunakan SwaggerUI untuk melihat dokumentasi API

Jika kami menghantar dokumentasi yang dijana terus kepada pembangun bahagian hadapan, ia akan membawa tekanan yang tidak perlu kepada mereka. Untuk menjadikan dokumentasi API lebih mesra dan lebih mudah digunakan, kami boleh memperkenalkan SwaggerUI untuk melihat dokumentasi API.

Mula-mula kita perlu menyalin fail sumber statik SwaggerUI ke projek kita Kemudian, kita boleh mencipta Penghala dengan laluan /swagger/*sebarang untuk mengaitkan SwaggerUI dengan projek kami:

r.StaticFS("/swagger", http.Dir("docs"))

Seterusnya. , lawati http://localhost:8080/swagger/index.html dalam penyemak imbas untuk melihat dokumen API yang dijana secara automatik.

Ringkasan

Menggunakan Swagger dalam Beego, anda boleh menyeragamkan takrif API melalui anotasi dan menjana dokumen API yang cantik untuk kegunaan mudah oleh pembangun. Pada masa yang sama, pengenalan SwaggerUI dapat memudahkan lagi paparan dan interaksi API serta mempercepatkan pembangunan.

Bahan rujukan:

https://www.cnblogs.com/wuyun-blog/p/10540875.html

https://github.com/swaggo/ gin-swagger

https://github.com/swaggo/swag

Atas ialah kandungan terperinci Gunakan Swagger untuk menjana dokumen API secara automatik dalam Beego. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!