gin-swagger生成API文档

github地址：https://github.com/swaggo/gin-swagger

 

下载安装cmd/swag命令工具包

先下载cmd包，才能执行相关命令

go get -u github.com/swaggo/swag/cmd/swag

我开始没成功，后来进入$GOPATH/bin/ 目录执行go get github.com/swaggo/swag/cmd/swag ，在bin目录下生成一个swag.exe文件，把$GOPATH/bin/ 添加到Path环境变量才算成功

回到顶部

执行初始化命令

swag init  // 注意，一定要和main.go处于同一级目录

初始化命令，在根目录生成一个docs文件夹

• docs/docs.go

回到顶部

示例程序

package main

import (
    "apiwendang/controller"
    _ "apiwendang/docs"
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)


// @title Docker监控服务
// @version 1.0
// @description docker监控服务后端API接口文档

// @contact.name API Support
// @contact.url http://www.swagger.io/support

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:9009
// @BasePath
func main() {
    r := gin.New()

    r.Use(Cors())
    //url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
    r.POST("/test/:id", controller.Test)
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run(":9009")
}


func Cors() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Header("Access-Control-Allow-Origin", "*")
        c.Next()
    }
}

回到顶部

再次执行初始化命令

swag init  // 注意，一定要和main.go处于同一级目录

初始化命令，在根目录生成一个docs文件夹，内含三个文件

• docs/docs.go
• swagger.json
• swagger.yaml

访问swagger文档：http://localhost:9009/swagger/index.html

====

回到顶部

API操作

// @Summary 接口概要说明
// @Description 接口详细描述信息
// @Tags 用户信息   //swagger API分类标签, 同一个tag为一组
// @accept json  //浏览器可处理数据类型，浏览器默认发 Accept: */*
// @Produce  json  //设置返回数据的类型和编码
// @Param id path int true "ID"    //url参数：（name；参数类型[query(?id=),path(/123)]；数据类型；required；参数描述）
// @Param name query string false "name"
// @Success 200 {object} Res {"code":200,"data":null,"msg":""}  //成功返回的数据结构， 最后是示例
// @Failure 400 {object} Res {"code":200,"data":null,"msg":""}
// @Router /test/{id} [get]    //路由信息，一定要写上

如果参数是body

// @Param user body models.User true "user"

1. 返回字符串

// @Summary 测试接口
// @Description 描述信息
// @Success 200 {string} string    "ok"
// @Router / [get]
func Test(ctx *gin.Context)  {
    ctx.JSON(200, "ok")
}

 2. 返回gin.H

// @Summary 测试接口
// @Description 描述信息
// @Success 200 {object} gin.H
// @Router / [get]
func Test(ctx *gin.Context)  {
    ctx.JSON(200, gin.H{
        "code":200,
    })
}

如果直接返回gin.H这种json结构，要用@Success 200 {object} gin.H，但是这种编译很慢，最好还是返回一种固定的结构体

3. 返回固定struct结构体

type Res struct {
    Code int `json:"code"`
    Data interface{} `json:"data"`
    Msg string `json:"msg"`
}
func returnMsg(ctx *gin.Context, code int, data interface{}, msg string) {
    ctx.JSON(200, Res{
        Code:code,
        Data:data,
        Msg:msg,
    })
}

// @Summary 测试接口
// @Description 描述信息
// @Success 200 {object} Res {"code":200,"data":null,"msg":""}
// @Router / [get]
func Test(ctx *gin.Context)  {
    ctx.JSON(200, Res{
        Code:200,
        Data:nil,
        Msg:"",
    })
}

 POST请求：

models/user.go
  
type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}
==================

type Res struct {
    Code int `json:"code"`
    Data interface{} `json:"data"`
    Msg string `json:"msg"`
}
func returnMsg(ctx *gin.Context, code int, data interface{}, msg string) {
    ctx.JSON(200, Res{
        Code:code,
        Data:data,
        Msg:msg,
    })
}


func Test1(ctx *gin.Context)  {
    returnMsg(ctx, 500, "aaa", "bbb")
}

// @Summary 接口概要说明
// @Description 接口详细描述信息
// @Tags 测试
// @Security Bearer
// @Produce  json
// @Param id path int true "ID"
// @Param user body models.User true "user"
// @Success 200 {object} Res {"code":200,"data":null,"msg":""}
// @Router /test/{id} [post]
func Test(ctx *gin.Context)  {
    fmt.Println(ctx.Param("id"))
    var input models.User
    if err := ctx.ShouldBindJSON(&input); err!=nil{
        returnMsg(ctx, 402, nil, err.Error())
        return
    }
    fmt.Println(input)
    returnMsg(ctx, 200, "aaa", "bbb")
}

回到顶部

如果出现错误：Undocumented   TypeError: Failed to fetch

查看具体错误信息，浏览器F12，发现是跨域问题：

Failed to load http://127.0.0.1:9009/test/2: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:9009' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

设置允许跨域就OK了

简单版本：

func Cors() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Header("Access-Control-Allow-Origin", "*")
        c.Next()
    }
}

复杂的可以根据实际需求添加：

func Cors() gin.HandlerFunc {
    return func(c *gin.Context) {
        method := c.Request.Method  
        origin := c.Request.Header.Get("Origin")
        var headerKeys []string
        for k, _ := range c.Request.Header {
            headerKeys = append(headerKeys, k)
        }
        headerStr := strings.Join(headerKeys, ", ")
        if headerStr != "" {
            headerStr = fmt.Sprintf("access-control-allow-origin, access-control-allow-headers, %s", headerStr)
        } else {
            headerStr = "access-control-allow-origin, access-control-allow-headers"
        }
        if origin != "" {
            c.Writer.Header().Set("Access-Control-Allow-Origin", "*")
            c.Header("Access-Control-Allow-Origin", "*")                                       // 这是允许访问所有域
            c.Header("Access-Control-Allow-Methods", "POST, GET, OPTIONS, PUT, DELETE,UPDATE") //服务器支持的所有跨域请求的方法,为了避免浏览次请求的多次'预检'请求
            //  header的类型
            c.Header("Access-Control-Allow-Headers", "Authorization, Content-Length, X-CSRF-Token, Token,session,X_Requested_With,Accept, Origin, Host, Connection, Accept-Encoding, Accept-Language,DNT, X-CustomHeader, Keep-Alive, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Pragma")
            //              允许跨域设置                                                                                                      可以返回其他子段
            c.Header("Access-Control-Expose-Headers", "Content-Length, Access-Control-Allow-Origin, Access-Control-Allow-Headers,Cache-Control,Content-Language,Content-Type,Expires,Last-Modified,Pragma,FooBar") // 跨域关键设置 让浏览器可以解析
            c.Header("Access-Control-Max-Age", "172800")                                                                                                                                                           // 缓存请求信息 单位为秒
            c.Header("Access-Control-Allow-Credentials", "false")                                                                                                                                                  //  跨域请求是否需要带cookie信息 默认设置为true
            c.Set("content-type", "application/json")                                                                                                                                                              // 设置返回格式是json
        }

        //放行所有OPTIONS方法
        //if method == "OPTIONS" {
        //    c.JSON(http.StatusOK, "Options Request!")
        //}
        if method == "OPTIONS" {
            c.AbortWithStatus(204)
            return
        }
        // 处理请求
        c.Next() //  处理请求
    }
}

https://www.ctolib.com/swaggo-swag.html

https://github.com/swaggo/swag

原文 https://www.cnblogs.com/zhzhlong/p/11800787.html