Gin框架中配置Swagger（完整流程版）

一 Swagger 简介

Swagger是一个API文档工具，可以用于自动生成、描述、调试和可视化RESTful API文档。其通过标准化API的描述格式和工具链，帮助开发者快速创建和部署API。

二 开始配置

2.1 安装swag并引入依赖

// 安装swag
go get -u github.com/swaggo/swag/cmd/swag
// 引入依赖
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2.2 在接口加上swagger注释（手动加入）

举例子如下：

2.2.1 Get请求：

// GetTodo
// @Summary Get All todoList
// @Description Get All todoList by creator (base or vip)
// @Tags todos
// @Accept json
// @Produce json
// @Param creator query string true "Creator"
// @Success 200 {string} string "ok"
// @Failure 400 {string} string "bad request"
// @Failure 500 {string} string "Internal Server Error"
// @Router /todos [get]
func GetTodo(ctx *gin.Context) {}

逐行进行解释：

// GetTodo : 用于标识这个接口的名称。
// @Summary Get All todoList：用于描述该接口的简要概述。
// @Description Get All todoList by creator (base or vip)：用于描述该接口的详细描述。
// @Tags todos：用于将该接口与 todos 标签相关联。
// @Accept json：用于指定该接口接受的请求头类型。
// @Produce json：用于指定该接口响应的响应头类型。
// @Param creator query string true “Creator”：用于定义一个请求参数，其中 creator 是参数名称，query 表示它是一个查询参数，string 表示参数类型，true 表示这是一个必需的参数，最后的 “Creator” 是该参数的描述信息。
// @Success 200 {string} string “ok”：用于定义一个成功响应，其中 200 表示响应状态码，{string} 表示响应的数据类型，string 表示响应的数据类型的描述信息，“ok” 表示响应的数据的描述信息。
// @Failure 400 {string} string “bad request”：用于定义一个失败响应，其中 400 表示响应状态码，{string} 表示响应的数据类型，string 表示响应的数据类型的描述信息，“bad request” 表示响应的数据的描述信息。
// @Failure 500 {string} string “Internal Server Error”：用于定义一个失败响应，其中 500 表示响应状态码，{string} 表示响应的数据类型，string 表示响应的数据类型的描述信息，“Internal Server Error” 表示响应的数据的描述信息。
// @Router /todos [get]：用于定义路由信息，其中 /todos 是接口路径，[get] 表示请求方法为GET。

2.2.2 Post请求：

// CreateTodo
// @Summary Create a mytodo
// @Description Create a mytodo by GetTodoReq (base or vip)
// @Tags todos
// @Accept json
// @Produce json
// @Param req body GetTodoReq true "create todoList request message"
// @Success 200 {string} string "ok"
// @Failure 400 {string} string "bad request"
// @Failure 500 {string} string "Internal Server Error"
// @Router /todos [post]
func CreateTodo(ctx *gin.Context) {}

对与Get请求写法不一样的行进行解释：

// @Param req body GetTodoReq true “create todoList request message”：表示接口需要一个名为req的参数，参数类型为请求体（body），请求体的数据结构为GetTodoReq，且为必填参数。后面的字符串为参数的描述信息。
// @Router /todos [post]：[post] 表示请求方法为post。

其中GetTodoReq就是自己定义的接受请求的请求体，例如：

// 对于不想在swaggerUI中展示的字段可以写成`json:"-"`即可
type GetTodoReq struct {
	Title   string `json:"title"`
	Content string `json:"content"`
	Creator string `json:"-"`
	Admin   bool   `json:"-"`
}

2.2.3 Put请求

// UpdateTodo
// @Summary Update a mytodo
// @Description Update a mytodo by title (base or vip)
// @Tags todos
// @Accept json
// @Produce json
// @Param req body GetTodoReq true "update todoList request message"
// @Success 200 {string} string "ok"
// @Failure 400 {string} string "bad request"
// @Failure 500 {string} string "Internal Server Error"
// @Router /todos [put]
func UpdateTodo(ctx *gin.Context) {}

2.2.4 Delete请求

// DeleteTodo
// @Summary Delete a mytodo
// @Description Delete a mytodo by title (base or vip)
// @Tags todos
// @Accept json
// @Produce json
// @Param title query string true "Title"
// @Success 200 {string} string "ok"
// @Failure 400 {string} string "bad request"
// @Failure 500 {string} string "Internal Server Error"
// @Router /todos [delete]
func DeleteTodo(ctx *gin.Context) {}

2.3 生成docs文件并registerSwagger

2.3.1 生成docs文件

在要使用的接口上配置好swagger注释后，在Terminal中使用下面的命令：

swag init

此时会遇到以下几种情况：

1. 如果报错了，则按照报错的内容调整自己接口上的注释，保证注释书写的正确。
2. 没报错的话则会自动在项目中生成下面的文件
   

特别要注意，只要你修改过swagger注释，为了生效，就要再执行一次 swag init 命令。

2.3.2 registerSwagger（还有其他的方式进行注册，这是我注册的方式）

route.go

package api
import (
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	docs "todo-list/docs"
)

func Route(r gin.IRouter) {
	// global
	registerSwagger(r)
	// api
	{
		g := r.Group("/api/v1")
		todo.RegisterTodo(g)
	}
}

func registerSwagger(r gin.IRouter) {
	// API文档访问地址: http://host/swagger/index.html
	// 注解定义可参考 https://github.com/swaggo/swag#declarative-comments-format
	// 样例 https://github.com/swaggo/swag/blob/master/example/basic/api/api.go
	docs.SwaggerInfo.BasePath = "/api/v1"
	docs.SwaggerInfo.Title = "管理后台接口"
	docs.SwaggerInfo.Description = "实现一个管理系统的后端API服务"
	docs.SwaggerInfo.Version = "1.0"
	docs.SwaggerInfo.Host = "localhost:8080"
	docs.SwaggerInfo.Schemes = []string{"http", "https"}
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
}

main.go

package main

func main() {
	r := gin.Default()
	api.Route(r)
	r.Run(":8080")
}

2.4 启动项目并打开SwaggerUI网页即可

先启动项目，然后打开浏览器访问http://localhost:8080/swagger/index.html即可。