Swaggo零基础入门教程

1. Swaggo是什么？

Swaggo是一个Go语言的API文档生成工具，它可以根据Go代码自动生成API文档，并且允许开发者在代码注释中添加API的参数、返回值、请求方法、请求路径等信息。使用Swaggo可以为自己的API提供完善的文档说明，方便其他开发者使用和维护。

1. 安装Swaggo

在开始使用Swaggo之前，需要先安装Swaggo。可以通过以下命令安装：

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

1. 使用Swaggo

在安装完Swaggo之后，可以根据以下步骤使用Swaggo：

3.1 添加注释

在Go代码中添加标准的注释，以便Swaggo可以根据注释生成API文档。在注释中需要包含API的请求方式、请求路径、请求参数、请求返回值等信息。

示例：

// @Summary add a new pet to the store
// @Description ""
// @Accept json
// @Produce json
// @Param pet body Pet true "Pet object that needs to be added to the store"
// @Success 200 {string} string "{"id": 0, "name": "string", "category": {"id": 0, "name": "string"}, "photoUrls": ["string"], "tags": [{"id": 0, "name": "string"}], "status": "available"}"
// @Failure 400 "Invalid input"
// @Failure 500 "Internal server error"
// @Router /pet [post]

3.2 生成文档

使用Swaggo命令行工具提供的命令可以生成文档。在项目根目录执行以下命令：

swag init

此时就会在项目中生成docs文件夹，其中包含了生成的文档信息。

3.3 查看文档

可以通过访问 http://localhost:8080/swagger/index.html 查看API文档。

1. 示例说明

4.1 示例一

代码片段：

// @Summary get user by ID
// @Description get user by ID
// @Tags Users
// @Accept  json
// @Produce  json
// @Param id path uint64 true "User ID"
// @Success 200 {object} User
// @Failure 400 {object} ErrorResponse
// @Router /user/{id} [get]
func getUser(w http.ResponseWriter, r *http.Request) {...}

在以上代码中，我们在注释中指定了API的请求方式(GET)，请求路径(/user/{id})、请求参数(id)、请求返回值和请求失败时的错误信息。执行 swag init 命令后生成的文档中，这个API信息就会被包含在其中。

4.2 示例二

代码片段：

// @Summary upload an image to the server
// @Description upload an image to the server
// @Tags Images
// @Accept  mpfd
// @Produce  json
// @Param image formData file true "image file to upload"
// @Success 200 {string} string
// @Failure 400 {object} ErrorResponse
// @Router /image/upload [post]
func uploadImage(w http.ResponseWriter, r *http.Request) {...}

在这个示例中，我们指定了API的请求方式(POST)，请求路径(/image/upload)、请求参数(image)、请求成功和失败时的返回值。对应的文档也会在执行 swag init 命令后生成。