基于golang的swagger

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

 

 

github:  swaggo/swag

 

一般步骤:

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

整体api说明:

annotationdescriptionexample
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

annotationdescriptionparametersexample
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 annotationexample
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说明:

annotationdescription
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 Typeannotation
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 NameTypeDescription
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 NameTypeDescription
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"` // 排序依据
}
复制代码
1
2
3
4
5
6
7
8
// 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 文件,写入如下注解:
复制代码
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// @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
posted @   X-Wolf  阅读(1654)  评论(0编辑  收藏  举报
相关博文:
阅读排行:
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 我与微信审核的“相爱相杀”看个人小程序副业
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· spring官宣接入deepseek,真的太香了~
历史上的今天:
2019-05-29 微信之语音存储
2018-05-29 VMware虚拟机中常见的问题汇总
2018-05-29 Windows10下安装VMware虚拟机并搭建CentOS系统环境
 
点击右上角即可分享
微信分享提示