Gin-Swagger的使用

最新推荐文章于 2024-05-17 15:34:14 发布

B_rownJay

最新推荐文章于 2024-05-17 15:34:14 发布

阅读量3.7k

点赞数 1

分类专栏： golang 文章标签： gin restful json

本文链接：https://blog.csdn.net/qq_51898139/article/details/126463726

版权

golang 专栏收录该内容

14 篇文章 1 订阅

订阅专栏

文章目录

前言
一、准备工作
二、添加注释
四、生成docs文件
三、注册路由
总结

前言

在写前后端分离的后端项目的时候，我们常常写后端程序返回的大多都是restful API风格的JSON数据，

而Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言，配合gin框架使用就可以自动生成一份接口文档包括自动文档，代码生成和测试用例生成。

一、准备工作

go get -u github.com/swaggo/swag/cmd/swag下载这个包方便我们使用swag命令

二、添加注释

注释一般添加在两个地方，一个是main函数里，另外就是添加到api接口函数里

main函数中

package main

// @title 这里写标题
// @version 这里写版本号
// @description 这里写描述信息
// @termsOfService http://swagger.io/terms/

// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 这里写接口服务的host
// @BasePath 这里写base path（eg：/api/v1）
func main() {

接口函数中

// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamArtList(请求参数结构体) false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponseArtList
// @Router /接口路由 [请求类型]
func GetArt(c *gin.Context) {

_ResponseArtList一般是在接口层再额外定义的用于swagger的结构体

// 文章列表接口数据信息
type _ResponseArticle struct {
	Code    int              `json:"code"`    //业务状态码
	Message string           `json:"message"` // 提示信息
	Data    *[]model.Article `json:"data"`    // 数据
}