1、安装
go get -u github.com/swaggo/swag/cmd/swag go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/files go get -u github.com/alecthomas/template
验证安装成功与否
$ swag -v swag version v1.8.8
2、写注释
注解说明
注解 | 描述 |
---|---|
@Summary | 摘要 |
@Produce | API 可以产生的 MIME 类型的列表,MIME 类型你可以简单的理解为响应类型,例如:json、xml、html 等等 |
@Param | 参数格式,从左到右分别为:参数名、入参类型、数据类型、是否必填、注释 |
@Success | 响应成功,从左到右分别为:状态码、参数类型、数据类型、注释 |
@Failure | 响应失败,从左到右分别为:状态码、参数类型、数据类型、注释 |
@Router | 路由,从左到右分别为:路由地址,HTTP 方法 |
实例:
// @title 博客系统 // @version 1.0 // @description Go 语言编程之旅:一起用 Go 做项目 // @termsOfService https://github.com/go-programming-tour-book func main() { global.Logger.Infof("%s: go-programming-tour-book/%s", "eddycjy", "blog-service") gin.SetMode(global.ServerSetting.RunMode) router := routers.NewRouter() s := &http.Server{ Addr: ":" + global.ServerSetting.HttpPort, Handler: router, ReadTimeout: global.ServerSetting.ReadTimeout, WriteTimeout: global.ServerSetting.WriteTimeout, MaxHeaderBytes: 1 << 20, } s.ListenAndServe() } // @Summary 获取多个标签 // @Produce json // @Param name query string false "标签名称" maxlength(100) // @Param state query int false "状态" Enums(0, 1) default(1) // @Param page query int false "页码" // @Param page_size query int false "每页数量" // @Success 200 {object} model.Tag "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags [get] func (t Tag) List(c *gin.Context) {} // @Summary 新增标签 // @Produce json // @Param name body string true "标签名称" minlength(3) maxlength(100) // @Param state body int false "状态" Enums(0, 1) default(1) // @Param created_by body string true "创建者" minlength(3) maxlength(100) // @Success 200 {object} model.Tag "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags [post] func (t Tag) Create(c *gin.Context) {} // @Summary 更新标签 // @Produce json // @Param id path int true "标签 ID" // @Param name body string false "标签名称" minlength(3) maxlength(100) // @Param state body int false "状态" Enums(0, 1) default(1) // @Param modified_by body string true "修改者" minlength(3) maxlength(100) // @Success 200 {array} model.Tag "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags/{id} [put] func (t Tag) Update(c *gin.Context) {} // @Summary 删除标签 // @Produce json // @Param id path int true "标签 ID" // @Success 200 {string} string "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags/{id} [delete] func (t Tag) Delete(c *gin.Context) {}
3、生成
swag init
在执行命令完毕后,会发现在 docs 文件夹生成 docs.go
、swagger.json
、swagger.yaml
三个文件。
4、路由
import ( ... _ "gin_blog/docs" //这里引入自己的docs swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" ) func NewRouter() *gin.Engine { r := gin.New() r.Use(gin.Logger()) r.Use(gin.Recovery()) r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) ... return r }
5、访问接口文档
在浏览器中访问 Swagger 的地址 http://127.0.0.1:8000/swagger/index.html
,就可以看到文档,其主要分为三个部分,分别是项目主体信息、接口路由信息、模型信息,这三部分共同组成了我们主体内容。
参考:
生成接口文档 | Go 语言编程之旅 (eddycjy.com)
(37条消息) 基于golang的swagger超贴心、超详细使用指南【有很多坑】_【阿冰】的博客-CSDN博客
标签:github,global,接口,文档,go,gin,swagger,com From: https://www.cnblogs.com/mango1997/p/16973735.html