文章目录

前言一、准备工作二、添加注释四、生成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"` // 数据

}

如果还想添加其他注释可以看文档添加需要的注释：swagger注释

四、生成docs文件

注释添加完毕之后就应该在终端输入swag init这样项目中就会多一个docs文件

三、注册路由

然后再在router里面注册路由 r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler)) 注意要把docs文件导入router里

总结

这样项目启动就可以访问http://localhost:port/swagger/index.html看到接口文档了

查看原文