Gin框架系列教程(5)- 项目集成swagger及注解简单应用

Swagger介绍:

Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。

支持 API 自动生成同步的在线文档:
使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。提供 Web 页面在线测试 API:
光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。

安装Swagger:

从 Go 1.17 开始,go get不推荐使用安装可执行文件。go install可以改用:

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

//是否安装成功
swag -v

项目使用:

导入

import (
    _ "gin_alingfeng/docs"


    swaggerfiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

主程序入口,以及swagger路由:

// @host         127.0.0.1:9000
// @schemes      http
// @Title        接口文档
// @version      v1.0
// @description  所有接口的方法,描述,参数,响应,文档,测试,仅供参考,有问题请及时联系管理员。
func main() {
	r := gin.Default()
	// 路由初始化
	routers.Routers(r)
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	// 数据库初始化
	models.Init()
	//启动
	r.Run(":9000")
}

api方法注解:(参数,可以单独写,也可以用结构体一起放进去)

// @Summary 新增用户
// @Description 新增用户
// @Tags User
// @Accept json
// @Param name body string true "姓名" example(不超过50字)
// @Param email body string false "邮箱" example(不超过50字)
// @Param account body string true "账号" example(不超过50字)
// @Param data query modules.User true "这里是介绍"
// @Produce json
// @Success 200 {string} string "{"success":200,"msg":"新增成功"}"
// @Failure 500 {string} Add 失败后返回值
// @Router /api/v1/user/add [post]
func Add(c *gin.Context) {
	c.String(200, "user add")
}


注意:每次修改了注释都需要重新init一下:

swag init

//其他用法
 swag init -dir ./cmd/ -output docs/api/ --pd true
 --dir main.go文件所在目录
 --output 输出目录
 --pd 从依赖关系中解析文件 默认false

用法描述:

// @Tags 每个API操作的标签列表,以逗号分隔,如分组
// @Summary 该操作的简短摘要,如api名称
// @Router 以空格分隔的路径定义。 格式:path,[httpMethod]
// @Accept 请求体接收的格式,值为Mime类型
// @param 请求参数用空格分隔的参数。
    param name,param type,data type,is mandatory?,comment,attribute(optional)
    1.参数名,2.参数类型,3.参数数据类型,4.是否必须,5.参数描述,6.其他属性
    其他属性详解:
        最大最小值 minimum(0.01),maximum(100)
        最大最小长度 minLength(1),maxLength(200)
        枚举值 Enums(A, B),Enums(1, 2),Enums(1.1, 2.2)
        示例 example(A)
        默认值 default(A)-选填

// @Produce 返回体返回的格式,值为Mime类型
// @Success 以空格分隔的成功响应。
    return code,{param type},data type,comment
    1.返回状态码,2.返回参数类型,3.返回数据,4.参数描述
// @failure 以空格分隔的故障响应。
    return code,{param type},data type,comment
1. 返回状态码,2.返回参数类型,3.返回数据,4.参数描述

// Response 定义业务处理响应类型
type Success_Response struct {
    Code RespCode `json:"code" example:"0"`
    Msg  string   `json:"msg" example:"操作成功"`
    Data RespData `json:"data" example:""`
} 

// Response 定义业务处理响应类型
type failure_Response struct {
    Code RespCode `json:"code" example:"1"`
    Msg  string   `json:"msg" example:"操作失败"`
    Data RespData `json:"data  example:""`
} 

type类型:

json: application/json,
x-www-form-urlencoded: application/x-www-form-urlencoded,
xml: text/xml,
plain: text/plain,

html: text/html,

mpfd: multipart/form-data,


json-api: application/vnd.api+json,


json-stream: application/x-json-stream,


octet-stream: application/octet-stream,



png: image/png,




jpeg: image/jpeg,




gif: image/gif,


数据类型:

● string (string)
● integer (int, uint, uint32, uint64)
● number (float32)
● boolean (bool)
● user defined struct


参数类型:

● query
● path
● header
● body
● formData


最后:

访问地址:构建您的应用程序,然后访问http://localhost:8080/swagger/index.html,您将看到您的 Swagger UI。

点赞1
点击评论0
收藏0
浏览 73
 

还没有评论,快来发表第一个评论吧

免责声明:凡在本网站出现的信息,均仅供参考。本网站将尽力确保所提供信息的准确性及可靠性,但不保证有关资料的准确性及可靠性,注册用户和一般页面游览者在使用前请进一步核实,并对任何自主决定的行为负责。本网站对有关资料所引致的错误、不确或遗漏,概不负任何法律责任(包括侵权责任、合同责任和其它责任)
*尊重作者,转载请注明出处!

创作内容

开启你的爱凌峰创作之旅

发布首篇内容,开通创作中心
快来成为爱凌峰创作者吧~

写文章

板块热门【Gin】