【Golang学习笔记】swagger自动化api文档生成

原创已于 2023-08-17 17:40:12 修改 · 746 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#golang #学习 #自动化

于 2023-02-21 11:46:15 首次发布

Golang 专栏收录该内容

8 篇文章

订阅专栏

本文档介绍了如何利用goswagger工具和gin框架生成并管理API文档。首先，通过goinstall和goget命令安装所需依赖。接着，创建项目目录和main.go文件，然后使用swaginit命令生成API文档。在main.go中，展示了如何使用gin和swaggo的注解定义接口和响应，并运行服务展示SwaggerUI。最后，通过访问SwaggerUI进行接口测试。

goswagger官方文档: https://goswagger.io/

1. 打开命令行,下载swag

go install github.com/swaggo/swag/cmd/swag@latest

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

在这里插入图片描述

2. 创建项目目录及main.go文件

在这里插入图片描述

3. 生成api文档

# 命令行切换到项目目录，生成api文档
cd .\swag_doc\
swag init

4. main.go文件及swagger常用注解

package main

import (
	_ "GO20230123/gin_study/swag_doc/docs" //swag生成的目录
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	gs "github.com/swaggo/gin-swagger"
)

type Response struct {
	Code int    `json:"code"` //响应码
	Msg  string `json:"msg"`  //描述
	Data any    `json:"data"` //具体的数据

}

// UserList 用户列表
// @Tags 用户管理
// @Summary 用户列表
// @Description 返回一个用户列表，可根据查询参数指定
// @Param limit query string false "返回多少条"
// @Router /api/users [get]
// @Produce json
// @Success 200 {object} Response
func UserList(c *gin.Context) {
	c.JSON(200, Response{0, "成功", 21})
}

// @title FixPng博客系统后端api文档
// @version 1.0
// @description 这是FixPng博客系统后端api文档
// @host 127.0.0.1:8080
// @BasePath /
func main() {
	router := gin.Default()
	router.GET("/api/users", UserList)
	router.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

	router.Run(":8080")
}

5.登录swagger

# 更新注解后需要重刷
swag init
# 跑起项目，可以直接在该文档中发送请求
http://127.0.0.1:8080/swagger/index.html

在这里插入图片描述