首页 > 其他分享> 文章详细

基于golang的swagger

2022-05-29 15:00:24 阅读：241 来源： 互联网

标签：基于接口 golang json go gin swagger com

Swagger 相关的工具集会根据 OpenAPI 规范去生成各式各类的与接口相关联的内容，常见的流程是编写注解 =》调用生成库-》生成标准描述文件 =》生成/导入到对应的 Swagger 工具。

一般步骤:

1.按照swagger要求给接口代码添加声明式注释

2.使用swag工具扫描代码自动生成api接口文档数据(docs/)

3.使用gin-swagger渲染在线接口文档页面

[安装]

$ 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

验证是否安装成功

swag -v
swag version v1.8.1

[添加注释]

1.在main主入口文件添加项目相关介绍信息

package main

// @title 这里写标题
// @version 1.0
// @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
func main() {
    r := gin.New()

    // liwenzhou.com ...

    r.Run()
}

2.在代码中处理请求的接口函数添加注释

// GetPostListHandler2 升级版帖子列表接口
// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamPostList false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponsePostList
// @Router /posts2 [get]
func GetPostListHandler2(c *gin.Context) {
    // GET请求参数(query string)：/api/v1/posts2?page=1&size=10&order=time
    // 初始化结构体时指定初始参数
    p := &models.ParamPostList{
        Page:  1,
        Size:  10,
        Order: models.OrderTime,
    }

    if err := c.ShouldBindQuery(p); err != nil {
        zap.L().Error("GetPostListHandler2 with invalid params", zap.Error(err))
        ResponseError(c, CodeInvalidParam)
        return
    }
    data, err := logic.GetPostListNew(p)
    // 获取数据
    if err != nil {
        zap.L().Error("logic.GetPostList() failed", zap.Error(err))
        ResponseError(c, CodeServerBusy)
        return
    }
    ResponseSuccess(c, data)
    // 返回响应
}

// bluebell/models/params.go

// ParamPostList 获取帖子列表query string参数
type ParamPostList struct {
    CommunityID int64  `json:"community_id" form:"community_id"`   // 可以为空
    Page        int64  `json:"page" form:"page" example:"1"`       // 页码
    Size        int64  `json:"size" form:"size" example:"10"`      // 每页数据量
    Order       string `json:"order" form:"order" example:"score"` // 排序依据
}

// bluebell/controller/docs_models.go

// _ResponsePostList 帖子列表接口响应数据
type _ResponsePostList struct {
	Code    ResCode                 `json:"code"`    // 业务响应状态码
	Message string                  `json:"message"` // 提示信息
	Data    []*models.ApiPostDetail `json:"data"`    // 数据
}

[生成接口文档数据]

swag init


./docs
├── docs.go
├── swagger.json
└── swagger.yaml

[渲染文档]

import (
    // liwenzhou.com ...

    _ "bluebell/docs"  // 千万不要忘了导入把你上一步生成的docs

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

    "github.com/gin-gonic/gin"
)


注册路由:
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

把你的项目程序运行起来，打开浏览器访问 http://localhost:8080/swagger/index.html 就能看到Swagger 2.0 Api文档了。

gin-swagger 同时还提供了 DisablingWrapHandler 函数，方便我们通过设置某些环境变量来禁用Swagger。例如：
r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))

此时如果将环境变量 NAME_OF_ENV_VARIABLE设置为任意值，则 /swagger/*any 将返回404响应，就像未指定路由时一样。

标签：基于,接口,golang,json,go,gin,swagger,com
来源： https://www.cnblogs.com/xingxia/p/golang_gin_swagger.html

本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；
2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；
3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；
4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；
5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。

ICode9

基于golang的swagger