基于golang的swagger

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

github:  ​​swaggo/swag​​

一般步骤:

1.按照swagger要求给接口代码添加声明式注释(​​https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html​​)

整体api说明:

Security

​​Example​​

具体的API说明:

Example

​​celler/controller​​

Limitation

• Not supported for cross-package models. Only search in project root folder.​​See #39​​

Mime Types

Security

General API info.

// @securityDefinitions.basic BasicAuth

// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information

Each API operation.

// @Security ApiKeyAuth

Make it AND condition

// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]

Param Type

• object (struct)
• string (string)
• integer (int, uint, uint32, uint64)
• number (float32)
• boolean (bool)
• array

Data Type

• string (string)
• integer (int, uint, uint32, uint64)
• number (float32)
• boolean (bool)
• user defined struct

Attribute

// @Param enumstring query string false "string enums" Enums(A, B, C)
// @Param enumint query int false "int enums" Enums(1, 2, 3)
// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
// @Param string query string false "string valid" minlength(5) maxlength(10)
// @Param int query int false "int valid" mininum(1) maxinum(10)
// @Param default query string false "string default" default(A)

Available

Future

TIPS

User defined structure with an array type

// @Success 200 {array} model.Account <-- This is a user defined struct.

package model

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
}

Use multiple path params

/// ...
// @Param group_id path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get]

Example value of struct

type Account struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"account name"`
    PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
}

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"`    // 数据
}

注解部分说明:

注解    描述
@Summary    摘要
@Produce    API 可以产生的 MIME 类型的列表，MIME 类型你可以简单的理解为响应类型，例如：json、xml、html 等等
@Param    参数格式，从左到右分别为：参数名、入参类型、数据类型、是否必填、注释
@Success    响应成功，从左到右分别为：状态码、参数类型、数据类型、注释
@Failure    响应失败，从左到右分别为：状态码、参数类型、数据类型、注释
@Router    路由，从左到右分别为：路由地址，HTTP 方法
2.4.4.1 API
我们切换到项目目录下的 internal/routers/api/v1 目录，打开 tag.go 文件，写入如下注解：

// @Summary 获取多个标签
// @Produce  json
// @Param name query string false "标签名称" maxlength(100)
// @Param state query int false "状态" Enums(0, 1) default(1)
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags [get]
func (t Tag) List(c *gin.Context) {}

// @Summary 新增标签
// @Produce  json
// @Param name body string true "标签名称" minlength(3) maxlength(100)
// @Param state body int false "状态" Enums(0, 1) default(1)
// @Param created_by body string true "创建者" minlength(3) maxlength(100)
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags [post]
func (t Tag) Create(c *gin.Context) {}

// @Summary 更新标签
// @Produce  json
// @Param id path int true "标签 ID"
// @Param name body string false "标签名称" minlength(3) maxlength(100)
// @Param state body int false "状态" Enums(0, 1) default(1)
// @Param modified_by body string true "修改者" minlength(3) maxlength(100)
// @Success 200 {array} model.Tag "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags/{id} [put]
func (t Tag) Update(c *gin.Context) {}

// @Summary 删除标签
// @Produce  json
// @Param id path int true "标签 ID"
// @Success 200 {string} string "成功"
// @Failure 400 {object} errcode.Error "请求错误"
// @Failure 500 {object} errcode.Error "内部错误"
// @Router /api/v1/tags/{id} [delete]
func (t Tag) Delete(c *gin.Context) {}

[生成接口文档数据]

swag init

--generallinfo value  指定go项目入口文件, 默认是main.go
--swagger value   配置输出的文件的目录 默认 ./docs/swagger


./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响应，就像未指定路由时一样。