go post 参数_go语言使用Swaggo详细教程

最新推荐文章于 2024-07-04 20:53:07 发布
最新推荐文章于 2024-07-04 20:53:07 发布
阅读量1.5k 收藏
点赞数 1
文章标签： go post 参数

相信很多程序猿和我一样不喜欢写API文档。写代码多舒服，写文档不仅要花费大量的时间，有时候还不能做到面面具全。但API文档是必不可少的，相信其重要性就不用我说了，一份含糊的文档甚至能让前后端人员打起来。 而今天这篇博客介绍的swaggo就是让你只需要专注于代码就可以生成完美API文档的工具。废话说的有点多，我们直接看文章。

go语言中文文档：www.topgoer.com

大概最后文档效果是这样的：

6d8c17a2072da770dd490714d7d3c463.png

1.1.1. 关于Swaggo

或许你使用过Swagger, 而 swaggo就是代替了你手动编写yaml的部分。只要通过一个命令就可以将注释转换成文档，这让我们可以更加专注于代码。

目前swaggo主要实现了swagger 2.0 的以下部分功能：

  • 基本结构(Basic Structure)
  • API 地址与基本路径(API Host and Base Path)
  • 路径与操作 (Paths and Operations)
  • 参数描述(Describing Parameters)
  • 请求参数描述(Describing Request Body)
  • 返回描述(Describing Responses)
  • MIME 类型(MIME Types)
  • 认证(Authentication)Basic AuthenticationAPI Keys
  • 添加实例(Adding Examples)
  • 文件上传(File Upload)
  • 枚举(Enums)
  • 按标签分组(Grouping Operations With Tags)
  • 扩展(Swagger Extensions)

下文内容均以gin-swaggo为例 这里是demo地址

1.1.2. 使用

安装swag cli 及下载相关包

要使用swaggo,首先需要安装swag cli。

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

然后我们还需要两个包。

# gin-swagger 中间件go get github.com/swaggo/gin-swagger# swagger 内置文件go get github.com/swaggo/gin-swagger/swaggerFiles

在main.go内添加注释

package mainimport (    "net/http"    "github.com/gin-gonic/gin"    _ "github.com/student/0509/docs"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles")// @title Swagger Example API// @version 1.0// @description This is a sample server celler server.// @termsOfService https://www.topgoer.com// @contact.name www.topgoer.com// @contact.url https://www.topgoer.com// @contact.email me@razeen.me// @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host 127.0.0.1:8080// @BasePath /api/v1func main() {    r := gin.Default()    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))    v1 := r.Group("/api/v1")    {        v1.GET("/hello", HandleHello)        // v1.POST("/login", HandleLogin)        // v1Auth := r.Use(HandleAuth)        // {        //     v1Auth.POST("/upload", HandleUpload)        //     v1Auth.GET("/list", HandleList)        // }    }    r.Run(":8080")}

如上所示，我们需要导入

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

同时，添加注释。其中：

  • titile: 文档标题
  • version: 版本
  • description,termsOfService,contact ... 这些都是一些声明，可不写。
  • license.name 额，这个是必须的。
  • host,BasePath: 如果你想直接swagger调试API，这两项需要填写正确。前者为服务文档的端口，ip。后者为基础路径，像我这里就是“/api/v1”。
  • 在原文档中还有securityDefinitions.basic,securityDefinitions.apikey等，这些都是用来做认证的，我这里暂不展开。

到这里，我们在mian.go同目录下执行swag init就可以自动生成文档，如下：

E:goprojectsrcgithub.comopgoer>swag init2020/05/13 16:28:02 Generate swagger docs....2020/05/13 16:28:02 Generate general API Info, search dir:./2020/05/13 16:28:02 create docs.go at  docs/docs.go2020/05/13 16:28:02 create swagger.json at  docs/swagger.json2020/05/13 16:28:02 create swagger.yaml at  docs/swagger.yaml

然后我们在main.go导入这个自动生成的docs包，运行：

package mainimport (    "github.com/gin-gonic/gin"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles"    _ "github.com/razeencheng/demo-go/swaggo-gin/docs")// @title Swagger Example API// @version 1.0// ...
E:goprojectsrcgithub.comopgoer>go run main.go[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production. - using env:   export GIN_MODE=release - using code:  gin.SetMode(gin.ReleaseMode)[GIN-debug] GET    /swagger/*any             --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (3 handlers)[GIN-debug] GET    /api/v1/hello             --> main.HandleHello (3 handlers)[GIN-debug] Listening and serving HTTP on :8080

浏览器打开http://127.0.0.1:8080/swagger/index.html, 我们可以看到如下文档标题已经生成。

6f9d843fd3cc4200d6cd510c00e6397c.png

1.1.3. 在Handle函数上添加注释

接下来，我们需要在每个路由处理函数上加上注释，如：

package mainimport (    "net/http"    "github.com/gin-gonic/gin"    _ "github.com/student/0509/docs"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles")// @title Swagger Example API// @version 1.0// @description This is a sample server celler server.// @termsOfService https://www.topgoer.com// @contact.name www.topgoer.com// @contact.url https://www.topgoer.com// @contact.email me@razeen.me// @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host 127.0.0.1:8080// @BasePath /api/v1func main() {    r := gin.Default()    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))    v1 := r.Group("/api/v1")    {        v1.GET("/hello", HandleHello)        // v1.POST("/login", HandleLogin)        // v1Auth := r.Use(HandleAuth)        // {        //     v1Auth.POST("/upload", HandleUpload)        //     v1Auth.GET("/list", HandleList)        // }    }    r.Run(":8080")}// @Summary 测试SayHello// @Description 向你说Hello// @Tags 测试// @Accept json// @Param who query string true "人名"// @Success 200 {string} string "{"msg": "hello Razeen"}"// @Failure 400 {string} string "{"msg": "who are you"}"// @Router /hello [get]func HandleHello(c *gin.Context) {    who := c.Query("who")    if who == "" {        c.JSON(http.StatusBadRequest, gin.H{"msg": "who are u?"})        return    }    c.JSON(http.StatusOK, gin.H{"msg": "hello " + who})}

我们再次swag init, 运行一下。

bd316e83f342960694a94a53496645a3.png

此时，该API的相关描述已经生成了，我们点击Try it out还可以直接测试该API。

9a57101035e92656c356a6f242d37f70.png

是不是很好用，当然这并没有结束，这些注释字段，我们一个个解释。

27162cd3d61cdb1126fd36451f0aa0eb.png

这些注释对应出现在API文档的位置，我在上图中已经标出，这里我们主要详细说说下面参数：

Tags

Tags 是用来给API分组的。

Accept

接收的参数类型，支持表单(mpfd) 和 JSON(json)

Produce

返回的数据结构，一般都是json, 其他支持如下表：

Mime Type声明application/jsonjsontext/xmlxmltext/plainplainhtmlhtmlmultipart/form-datampfdapplication/x-www-form-urlencodedx-www-form-urlencodedapplication/vnd.api+jsonjson-apiapplication/x-json-streamjson-streamapplication/octet-streamoctet-streamimage/pngpngimage/jpegjpegimage/gifgif

Param

参数，从前往后分别是：

@Param 1.参数名 2.参数类型 3.参数数据类型 4.是否必须 5.参数描述 6.其他属性

  • 1.参数名参数名就是我们解释参数的名字。
  • 2.参数类型参数类型主要有三种：path 该类型参数直接拼接在URL中，如Demo中HandleGetFile：// @Param id path integer true "文件ID" query 该类型参数一般是组合在URL中的，如Demo中HandleHello// @Param who query string true "人名" formData 该类型参数一般是POST,PUT方法所用，如Demo中HandleLogin// @Param user formData string true "用户名" default(admin)
  • 3.参数数据类型数据类型主要支持一下几种：string (string)integer (int, uint, uint32, uint64)number (float32)boolean (bool)注意，如果你是上传文件可以使用file, 但参数类型一定是formData, 如下：// @Param file formData file true "文件"
  • 4.是否是必须表明该参数是否是必须需要的，必须的在文档中会黑体标出，测试时必须填写。
  • 5.参数描述就是参数的一些说明
  • 6.其他属性除了上面这些属性外，我们还可以为该参数填写一些额外的属性，如枚举，默认值，值范围等。如下：枚举 // @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) 而且这些参数是可以组合使用的，如：// @Param enumstring query string false "string enums" Enums(A, B, C) default(A) Success

指定成功响应的数据。格式为：

// @Success 1.HTTP响应码 {2.响应参数类型} 3.响应数据类型 4.其他描述

  • 1.HTTP响应码也就是200，400，500那些。
  • 2.响应参数类型 / 3.响应数据类型返回的数据类型，可以是自定义类型，可以是json。自定义类型在平常的使用中，我都会返回一些指定的模型序列化JSON的数据，这时，就可以这么写：// @Success 200 {object} main.File 其中，模型直接用包名.模型即可。你会说，假如我返回模型数组怎么办？这时你可以这么写：// @Success 200 {anrry} main.File json将如你只是返回其他的json数据可如下写：// @Success 200 {string} json ""
  • 4.其他描述可以添加一些说明。
Failure

​ 同Success。

Router

​ 指定路由与HTTP方法。格式为：

// @Router /path/to/handle [HTTP方法]

​ 不用加基础路径哦。

1.1.4. 生成文档与测试

其实上面已经穿插的介绍了。

在main.go下运行swag init即可生成和更新文档。

点击文档中的Try it out即可测试。 如果部分API需要登陆，可以Try登陆接口即可。

1.1.5. 优化

看到这里，基本可以使用了。但文档一般只是我们测试的时候需要，当我的产品上线后，接口文档是不应该给用户的，而且带有接口文档的包也会大很多(swaggo是直接build到二进制里的)。

想要处理这种情况，我们可以在编译的时候优化一下，如利用build tag来控制是否编译文档。

在main.go声明swagHandler,并在该参数不为空时才加入路由：

package main//...var swagHandler gin.HandlerFuncfunc main(){    // ...        if swagHandler != nil {            r.GET("/swagger/*any", swagHandler)        }    //...}

同时,我们将该参数在另外加了build tag的包中初始化。

// +build docpackage mainimport (    _ "github.com/razeencheng/demo-go/swaggo-gin/docs"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles")func init() {    swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)}

之后我们就可以使用go build -tags "doc"来打包带文档的包，直接go build来打包不带文档的包。

你会发现，即使我这么小的Demo,编译后的大小也要相差19M !

➜  swaggo-gin git:(master) ✗ go build➜  swaggo-gin git:(master) ✗ ll swaggo-gin-rwxr-xr-x  1 xxx  staff    15M Jan 13 00:23 swaggo-gin➜  swaggo-gin git:(master) ✗ go build -tags "doc"➜  swaggo-gin git:(master) ✗ ll swaggo-gin-rwxr-xr-x  1 xxx  staff    34M Jan 13 00:24 swaggo-gin

文章到这里也就结束了，完整的Demo地址在这里。

相关链接

  • Swaggo Github
  • Swagger
weixin_39673742
关注
  • 1
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
golang工程组件篇Api文档管理go-swagger之RESTful API设计规范
SMILY12138的博客
05-29 311
遵循RESTful API设计规范、提供Swagger UI展示API文档、使用go-swagger生成代码和文档、定义响应状态码、提供安全性措施、编写示例代码以及更新并维护文档是创建高质量API文档的关键步骤。Go-Swagger是一个RESTful API设计规范，它提供了一些基本的工具和命令行界面来创建、维护和生成API文档。使用Go-Swagger可以帮助您更轻松地管理API文档，并提高API设计的质量。Swagger UI是一个可视化工具，可以帮助您更好地展示API文档并测试您的API端点。
golang restful 框架之 go-swagger
hatlonely的专栏
02-09 7109
restful 是这些年的高频词汇了，各大互联网公司也都纷纷推出了自己的 restful api，其实 restful 和 thrift，grpc 类似，就是一种协议，但是这种协议有点特殊的就是使用 http 接口，返回的对象一般是 json 格式，这样有个好处，就是可以供前端的 js 直接调用，使用非常方便，但 http 本身并不是一个高效的协议，后端的内部通信还是使用 grpc 或者 thri...
go——Swagger使用
最新发布
weixin_57023347的博客
07-04 928
Swagger是一个用于设计，构建和文档化API的开源框架。在Go语言中，Swagger可以帮助后端开发人员快速创建和定义RESTful API，并提供，这些文档包含了API的详细信息以及如何使用他们的说明。RESTful是一个网络应用程序的设计风格，基于HTTP协议。使用XML或JSON格式定义统一标准接口。强调资源，统一接口，URL和无状态的设计风格。不是标准也不是协议，只是一种风格。
Go 语言 API 文档 又称 Golang
01-13
Go API文档。Go（又称 Golang）是 Google 的 Robert Griesemer，Rob Pike 及 Ken Thompson 开发的一种静态强类型、编译型语言。Go 语言语法与 C 相近，但功能上有：内存安全，GC（垃圾回收），结构形态及 CSP-style 并发计算。
golang api 生成文档
qq_43047481的博客
02-26 708
golang api 生成文档,导出文档接口 废话少数直接上代码: //如何生成一个简单的文档,代码如下: //先导入github.com/360EntSecGroup-Skylar/excelize/v2包 f := excelize.NewFile() // 创建一个工作表 index := f.NewSheet("Sheet2") // 设置单元格的值 f.SetCellValue("Sheet2", "A2", "Hello world.") f.Se
Apache License-中文版（转)
seawavecau的专栏
05-06 2435
Apache许可证2.0版 2004年1月http://www.apache.org/licenses/关于使用、复制和分发的条款 定义 "许可证"是指根据本文件第1到第9部分关于使用、复制和分发的条款。 "许可证颁发者"是指版权所有者或者由版权所有者授权许可证的实体。 "法律实体"是指实施实体和进行控制的所有其它实体受该实体控制，或者受该实体集中控制。根据此定义，"控制"是指(i)让无论是否签...
Go语言中的gin框架之GET/POST请求参数接收传值（五）
06-15
本教程将详细讲解如何在Gin中接收GET和POST请求的参数。 首先，我们需要引入Gin库。在`go.mod`文件中，确保你有以下依赖： ```go module example.com/gin_get_post go 1.14 require ( github....
go-json.zip_Go_ Go_ Go!_HTTP+JSON_JSON_golang web_发送json
09-23
在Go语言中，HTTP服务和JSON的处理是Web开发中的基础部分。`go-json.zip`这个压缩包可能包含了关于如何在Go中构建一个简单的HTTP服务器并处理JSON数据的示例代码。下面，我们将深入探讨Go语言中HTTP服务的创建、JSON...
Go语言服务器开发实现最简单HTTP的GET与POST接口
12-26
本文实例讲述了Go语言服务器开发实现最简单HTTP的GET与POST接口。分享给大家供大家参考。具体分析如下： Go语言提供了http包，可以很轻松的开发http接口。以下为示例代码： 代码如下:package webserver    import...
语音听写，go语言iat_go_demo
03-02
req, _ := http.NewRequest("POST", "http://api.xfyun.cn/v1/service/v1/iat", strings.NewReader(res_body)) req.Header.Set("X-Appid", appid) req.Header.Set("Content-Type", "application/x-...
跟我一起学Golang从入门到精通《Golang官方标准库API文档》
小啊宇的博客
09-08 1347
//Golang官方标准库API文档 ，https://golang.org/pkg可以查看所有包下的函数和使用 //1）API是Golang提供的基本编程接口 //2）Go语言提供了大量的标准库，因此google公司也为了这些标准库提供了相应 //的API文档，用于告诉开发者如何使用这些标准库，以及标准库包含的方法 //3）Golang中文网在线标准库文档：https://studygolang.com/pkgdoc //4）Golang的包和源文件和函数的关系简图 //Golang中，调用一个函数的方
Golang api 最新官方中文手册
03-06
Golang中文API,由热心网友翻译上传
swag.exe windows golang
01-02
swagger 文档生成器
golang-swaggerui-example:Golang的SwaggerUI生成示例
05-14
golang-swaggerui-example Golang-swaggerui-example是一个示例存储库，用于在您的Golang项目中使用SwaggerUI设置API文档。 详细说明可在。 API互动 可以通过访问localhost：8080 / swaggerui /访问SwaggerUI，有关如何服务/ swaggerui的详细说明，请参见博客文章。 笔记 Swagger.json不应位于您的git存储库中，而应由CI工具生成。 此处提供的代码未遵循任何标准。 它仅用于演示在简单的go项目中生成混乱规格的过程。 不要将此项目结构/实现用作您的Golang REST项目的参考。 执照 golang-swaggerui-example已获得MIT许可。 有关详细信息，请检查文件。 作者
Golang开发Web API服务器，echo框架集成Swagger快速开发API文档
Lyon_Nee的博客
06-13 1530
之前在公司用C# + ASP.Net Core开发Web API服务器中，用到Swagger这个插件来生成API文档觉得非常方便。 于是最近在学习golang开发Web API服务器的时候想着也集成Swagger到项目中，但是在网上找了很多文档都是不可行的，并且还很复杂，要么就是说一半的，写着写着不知道改怎么写了。 但是我不坑人，我接下来分享的我现在学习能够正常使用的方法，并且这篇博文我会在后面的使用过程中，有新的总结或者解决问题的方法都会更新出来。 这是要用到的github上的Swagger包链接，
Golang使用Swag搭建api文档
ninininiwowo的专栏
02-27 697
Golang使用Swag搭建api文档
查阅本地的Golang开发文档
.
01-18 1213
在windows环境下，下载安装好go开发环境后，在命令行模式下，执行godoc -http=:portID，如下图：然后在浏览器地址栏输入127.0.0.1:portID即可访问本地安装环境里面的go开发文档；(其中portID为端口号，可以随意填一个)，如下图：另一个方法是直接在命令模式下执行 godoc packageName 或 godoc packageName FuncName可以分别
[Go] Swaggo安装超时的解决
CnPeng
01-21 1279
1 问题现象 在 GOPATH 目录中通过 go get -u github.com/swaggo/swag/cmd/swag 安装 swag 时可能会遇见连接超时的错误信息，导致安装失败，如下： package golang.org/x/text/unicode/bidi: unrecognized import path "golang.org/x/text/unicode/bidi" (https fetch: Get https://golang.org/x/text/unicode/bidi?g
【swaggo】swaggo使用详解
SauryN的博客
12-26 4857
go 使用swagger工具swaggo，与gin集成
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值