Gunakan OpenAPI/Swagger untuk menulis dokumen API dalam bahasa Go

Dalam beberapa tahun kebelakangan ini, dengan pembangunan berterusan teknologi Internet, kepentingan antara muka API Web telah menjadi semakin penting, dan menulis dokumen API telah menjadi bahagian penting dalam kerja pembangunan. Dalam bahasa Go, kita boleh menggunakan OpenAPI/Swagger untuk menulis dokumen API.

OpenAPI/Swagger ialah spesifikasi API dan rantai alat yang boleh membantu kami membina dan menerangkan antara muka API yang mematuhi gaya seni bina RESTful. Ia mengandungi satu set bahasa penerangan API terpiawai dan satu siri alatan yang boleh membantu kami menjana dokumen API, kod klien dan rangka kerja pelayan secara automatik.

Dalam bahasa Go, anda boleh menggunakan "swag" pelaksanaan rasmi Swagger's Go untuk menjana dokumentasi API dengan cepat. Di bawah ini kita akan belajar cara menggunakan swag untuk menulis dokumentasi API.

Pertama, kita perlu menambah swag pada projek Anda boleh menggunakan arahan berikut untuk menambahkannya pada projek:

go get -u github.com/swaggo/swag/cmd/swag

Selepas memasang swag, kami perlu mengimport maklumat berkaitan swag dalam fail main.go Pakej:

import (
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
    "github.com/gin-gonic/gin"
)

// 注册swag
func setUpSwagger(engine *gin.Engine) {
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

func main() {
    // 初始化 gin 引擎
    engine := gin.Default()
    setUpSwagger(engine)
    router.LoadRouters(engine)
    _ = engine.Run()
}

Seterusnya, kita boleh menggunakan anotasi swagger untuk menerangkan antara muka dalam anotasi antara muka. Contohnya:

// User register router
// @Summary User register router
// @Description User register router
// @Tags Users
// @Accept  json
// @Produce  json
// @Param user_in body models.NewUser true "user info"
// @Success 200 {string} json "{"code":200,"data":null,"msg":"Register successful"}"
// @Failure 400 {string} json "{"code":400,"msg":"Bad Request"}"
// @Router /users/register [post]
func Register(c *gin.Context) {
    name := c.PostForm("name")
    password := c.PostForm("password")
    ...
}

Dalam ulasan, kami menggunakan beberapa anotasi sombong:

• @Ringkasan: Maklumat ringkasan antara muka
• @Penerangan: Penerangan terperinci antara muka
• @Tags: Teg antara muka
• @Terima: Permintaan antara muka Jenis Kandungan
• @Produce: Jenis Kandungan respons antara muka
• @Param: Perihalan parameter antara muka , termasuk kedudukan parameter, nama parameter, sama ada parameter yang diperlukan, perihalan parameter dan contoh parameter
• @Success: antara muka penerangan respons berjaya, yang boleh termasuk kod respons, maklumat respons dan struktur data respons
• @Kegagalan: Perihalan respons kegagalan antara muka, yang juga boleh memasukkan kod respons dan maklumat respons

Akhir sekali, kita perlu menggunakan perintah swag init dalam direktori akar projek untuk menjana dokumentasi API dihasilkan dalam direktori dokumen.

swag init

Kini, kita boleh melihat dokumentasi API dengan melawati http://localhost:8080/swagger/index.html.

Secara amnya, menggunakan OpenAPI/Swagger untuk menulis dokumentasi API boleh membantu kami menerangkan antara muka dengan lebih jelas dan menjadikannya lebih mudah dibaca dan difahami. Pustaka swag bahasa Go boleh menjana dokumen API dengan cepat, membolehkan kami membangun dengan lebih cekap.

Atas ialah kandungan terperinci Gunakan OpenAPI/Swagger untuk menulis dokumen API dalam bahasa Go. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!