gin 生成api文档_Golang使用Gin框架整合Swagger生成api文档

一、环境介绍

二、开始整合

1、安装swagger

2、Gin router代码

3、api代码

4、生成api配置文档

5、访问swagger

一、环境介绍

Go版本：1.13.1

开发工具：IntelliJ IDEA 2019.2.3 x64

开发环境：windows 10 64位

二、开始整合

代码目录结构

1、安装swagger

IDEA Terminal 项目根目录执行

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

2、Gin router代码

重点注意两点：

import _ “modulename/docs”

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

import (

_const "modulename/common/const"

_ "modulename/docs"

"github.com/gin-gonic/gin"

"github.com/swaggo/gin-swagger"

"github.com/swaggo/gin-swagger/swaggerFiles"

"log"

)

func InitHttpServer() {

var router *gin.Engine

router = gin.Default()

router.Static("/html", "./public")

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

router.Run(":" + _const.HTTP_SERVER_PORT)

}

3、api代码

一定要注意在方法上添加的注释，如果不规范，swagger不会识别

标准注释参见

https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html

// @Summary 根据条件查询实例

// @Description 根据条件查询实例

// @Accept json

// @Produce json

// @Param pageNum path int true "pageNum"

// @Param expName body string false "expName"

// @Param expType body string false "expType"

// @Param expTrade body string false "expTrade"

// @Param expScene body string false "expScene"

// @Param expRemark body string false "expRemark"

// @Param expDeg body int false "expDeg"

// @Param expCreateUser body string false "expCreateUser"

// @Success 200 {string} json "{"errcode":"200","data":"[{"expId":"111","expName":"TensorFlow","expType":"TensorFlow","expTrade":"制造业","expScene":"零售","expRemark":"零售零售零售零售","expDeg":"2","expCreateUser":"tfg"}]","msg":""}"

// @Failure 400 {string} json "{"errcode":"400","data":"","msg":"error......"}"

// @Router /api/v1/exp/list/{pageNum} [post]

func ListExp(c *gin.Context){

pageNum,err := strconv.Atoi(c.Param("pageNum"))

if err != nil {

rltStr := util.Rltjson( _const.SERVICE_FAIL_CODE,err.Error(),"")

c.String(http.StatusBadRequest, rltStr)

return

}

4、生成api配置文档

IDEA Terminal 项目根目录执行

swag init

会在项目根目录生成docs文件夹，docs文件有三个文件

5、访问swagger

启动服务。IDEA Terminal 项目根目录执行

go run main.go

浏览器访问http://localhost:port/swagger/index.html