Cara memasang swag untuk menjana dokumentasi API golang

Swag ialah alat untuk membina aplikasi Go dengan cepat, yang boleh menjana dokumentasi Swagger secara automatik. Pembangun boleh menjana dokumentasi API secara automatik dengan hanya menambahkan beberapa ulasan pada kod mereka. Swag menyokong penjanaan dokumen API mengikut piawaian API RESTful, dan juga menyokong penjanaan format Markdown dan HTML.

Dalam artikel ini, kami akan memperkenalkan cara memasang dan menggunakan Swag dalam golang.

Langkah 1 - Pasang Swag

Swag boleh dipasang dari GitHub menggunakan arahan go get Gunakan arahan berikut untuk memasang Swag:

$ go get github.com/swaggo/swag/cmd/swag

Selepas pemasangan. selesai, anda boleh memasangnya dalam $ Fail binari "swag" ditemui dalam laluan GOPATH/bin. Kini, kami boleh terus menggunakan Swag untuk menjana dokumentasi API.

Langkah 2 - Jana dokumentasi API

Swag memerlukan beberapa ulasan kod khas untuk menjana dokumentasi API dengan betul. Berikut ialah beberapa contoh ulasan:

// @Summary 创建用户
// @Description 创建一个新用户
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 200 {string} string "成功"
// @Failure 400 {string} string "请求错误"
// @Failure 500 {string} string "服务器内部错误"
// @Router /users [post]
func CreateUser(c *gin.Context) {
    // ...
}

Ulasan di atas menerangkan API tentang cara mencipta pengguna. Swag mencari ulasan istimewa ini dalam kod dan kemudian membina dokumentasi.

Laksanakan arahan berikut untuk menjana dokumentasi:

$ swag init

Ini akan mengimbas aplikasi anda dan menjana fail JSON Swagger dan UI Swagger.

Langkah 3 - Tambah UI Swagger

UI Swagger menyediakan antara muka interaktif untuk melihat dan menguji API. Kami boleh menambah UI Swagger pada aplikasi web kami.

// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/swaggo/files" // swagger embed files
    "github.com/swaggo/gin-swagger" // gin-swagger middleware
    _ "github.com/user/repo/docs" // docs is generated by Swag CLI, you have to import it.
)

func main() {
    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    //...
}

Andaikan anda telah menghasilkan dokumentasi menggunakan Swag. Kini anda boleh melihat dokumentasi API dengan membuka pautan berikut dalam penyemak imbas anda:

http://localhost:8080/swagger/index.html

Ini ialah UI Web Swagger yang boleh anda gunakan untuk melihat dan menguji API.

Ringkasan

Dalam artikel ini, kami memperkenalkan cara memasang dan menggunakan Swag di Golang. Dengan anotasi dan arahan Swagger, anda boleh menjana dokumentasi API dengan mudah. Swag menjadikan keseluruhan proses cepat dan mudah, dan dokumentasi menggunakan Swag disepadukan dengan baik dengan UI Swagger

Atas ialah kandungan terperinci Cara memasang swag untuk menjana dokumentasi API golang. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!