gin框架使用swagger自动生成接口文档在前后端分离项目中，如何维护接口文档是开发人员都遇到过的问题，因为前端开发人

在前后端分离项目中，如何维护接口文档是开发人员都遇到过的问题，因为前端开发人员、后端开发人员、测试人员等都需要看，此时如果有一份清晰明了的接口文档能够极大地提高各方方人员的沟通效率和开发效率。本文将介绍如何使用swagger自动生成接口文档。

什么是Swagger？

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

一、安装Swagger

在项目的根目录下执行以下命令：

go get -u github.com/swaggo/swag/cmd/swag  # Go1.17以前使用该命令
go install github.com/swaggo/swag/cmd/swag@latest  # Go1.17及之后的版本使用该命令
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

然后检验是否安装成功：

$ swag -v 
swag version v1.8.10   #安装成功

二、使用`gin-swagger` 自动生成接口文档

使用gin-swagger为项目自动生成接口文档，需要以下三个步骤：

(1) 写入注释：根据swagger规范为项目的API接口编写注释；

(2) 使用swag init命令生成API接口文档所需的文件；

(3)项目中集成swagger。

写入注释

假设有一个Article相关的服务，提供一些REST API，用于对文章数据的增删改查。

(1) 为项目添加注解

在程序入口main方法写入项目相关的信息

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

// @contact.name 这里写联系人名字
// @contact.email 这里写联系人邮箱
func main() {
	r := gin.New()
    //...........
	r.Run()
}

(2) 在Article的接口方法写入如下注解：

// @Summary 获取单个文章
// @Accept application/json
// @Produce application/json
// @Param id path int true "文章ID"
// @Success 200 {object} model.Article "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/articles/{id} [get]
func (a Article) Get(ctx *gin.Context) {}

// @Summary 获取多个文章
// @Produce json
// @Param name query string false "文章名称"
// @Param tag_id query int false "标签ID"
// @Param state query int false "状态"
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Success 200 {object} model.ArticleSwagger "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/articles [get]
func (a Article) List(ctx *gin.Context) {}

注解说明：

注解	描述
@Summary	对该接口的描述
@Accept	该接口接收请求的编码类型
@Produce	该接口返回的数据类型
@Param	表示参数，分别为：参数名称、参数类型、数据类型、是否必填、注解、属性(可选参数),参数之间用空格隔开
@Success	表示请求成功后返回，它有以下参数：请求返回状态码、参数类型、数据类型、注释
@Failure	表示请求失败后返回，它有以下参数：请求返回状态码、参数类型、数据类型、注解
@Router	路由，从左至右分别为：路由地址和HTTP方法

其中Param 的参数类型有以下几种：

query 形如 /articles?title=xxxxx&status=xxxx
body 需要将数据放到 body 中进行请求
path 形如 /articles/1

上述注解中，使用到了@Success 200 {object} model.ArticleSwagger "成功",我们专门定义一个针对Swagger的对象，用来Swagger接口文档的展示。在article.go文件中，定一个model：

type ArticleSwagger struct {
	List  []*Article
	Pager *app.Pager
}

生成文件

在根目录下，执行命令swag init，执行完成后会在根目录下新建一个 docs 文件夹，在该文件夹中生成docs.go,swagger.json ,swagger.yaml三个文件。

项目中集成swagger

在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容：

import (
	........
	_ "blog-app/docs"    // 不要忘了导入把你上一步生成的docs
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

三、查看接口文档

重启服务端，在浏览器中访问Swagger的地址http://127.0.0.1:8000/swagger/index.html，即可看到如下图所示的Swagger文档展示，其中主要分为三部分。分别是项目主题信息、接口路由信息和模型信息。

FireShot Capture 002 - Swagger UI - 127.0.0.1.png

gin框架使用swagger自动生成接口文档