基于golang的swagger

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

github:  swaggo/swag

一般步骤:

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

整体api说明:

annotation	description	example
title	Required. The title of the application.	// @title Swagger Example API
version	Required. Provides the version of the application API.	// @version 1.0
description	A short description of the application.	// @description This is a sample server celler server.
termsOfService	The Terms of Service for the API.	// @termsOfService http://swagger.io/terms/
contact.name	The contact information for the exposed API.	// @contact.name API Support
contact.url	The URL pointing to the contact information. MUST be in the format of a URL.	// @contact.url http://www.swagger.io/support
contact.email	The email address of the contact person/organization. MUST be in the format of an email address.	// @contact.email support@swagger.io
license.name	Required. The license name used for the API.	// @license.name Apache 2.0
license.url	A URL to the license used for the API. MUST be in the format of a URL.	// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host	The host (name or ip) serving the API.	// @host localhost:8080
BasePath	The base path on which the API is served.	// @BasePath /api/v1

Security

annotation	description	parameters	example
securitydefinitions.basic	Basic auth.		// @securityDefinitions.basic BasicAuth
securitydefinitions.apikey	API key auth.	in, name	// @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application	OAuth2 application auth.	tokenUrl, scope	// @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit	OAuth2 implicit auth.	authorizationUrl, scope	// @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password	OAuth2 password auth.	tokenUrl, scope	// @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode	OAuth2 access code auth.	tokenUrl, authorizationUrl, scope	// @securitydefinitions.oauth2.accessCode OAuth2AccessCode

parameters annotation	example
in	// @in header
name	// @name Authorization
tokenUrl	// @tokenUrl https://example.com/oauth/token
authorizationurl	// @authorizationurl https://example.com/oauth/authorize
scope.hoge	// @scope.write Grants write access

Example

具体的API说明:

annotation	description
description	A verbose explanation of the operation behavior.
id	A unique string used to identify the operation. Must be unique among all API operations.
tags	A list of tags to each API operation that separated by commas.
summary	A short summary of what the operation does.
accept	A list of MIME types the APIs can consume. Value MUST be as described under Mime Types.
produce	A list of MIME types the APIs can produce. Value MUST be as described under Mime Types.
param	Parameters that separated by spaces. param name,param type,data type,is mandatory?,comment attribute(optional)
security	Security to each API operation.
success	Success response that separated by spaces. return code,{param type},data type,comment
failure	Failure response that separated by spaces. return code,{param type},data type,comment
router	Failure response that separated by spaces. path,[httpMethod]

Example

celler/controller

Limitation

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

Mime Types

Mime Type	annotation
application/json	application/json, json
text/xml	text/xml, xml
text/plain	text/plain, plain
html	text/html, html
multipart/form-data	multipart/form-data, mpfd
application/x-www-form-urlencoded	application/x-www-form-urlencoded, x-www-form-urlencoded
application/vnd.api+json	application/vnd.api+json, json-api
application/x-json-stream	application/x-json-stream, json-stream
application/octet-stream	application/octet-stream, octet-stream
image/png	image/png, png
image/jpeg	image/jpeg, jpeg
image/gif	image/gif, gif

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

Field Name	Type	Description
default	*	Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined type for this parameter.
maximum	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
maxLength	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
minLength	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
enums	[*]	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.

Future

Field Name	Type	Description
format	string	The extending format for the previously mentioned type. See Data Type Formats for further details.
multipleOf	number	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
pattern	string	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
maxItems	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
minItems	integer	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
uniqueItems	boolean	See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.
collectionFormat	string	Determines the format of the array if type array is used. Possible values are: `csv` - comma separated values `foo,bar`. `ssv` - space separated values `foo bar`. `tsv` - tab separated values `foo\tbar`. `pipes` - pipe separated values foo|bar. `multi` - corresponds to multiple parameter instances instead of multiple values for a single instance `foo=bar&foo=baz`. This is valid only for parameters [`in`](#parameterIn) "query" or "formData". Default value is csv.

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


# 指定入口文件与输出路径
swag init -g cmd/app/main.go  -o ./docs

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

常见错误：

1.

Failed to load API definition

原因：

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

缺少这个初始化并注册操作

问题见：https://github.com/swaggo/swag/issues/830

参考文档:

• https://www.cnblogs.com/niuben/p/15634136.html