apache license 2.0如何使用防止法律纠纷_go语言使用Swaggo详细教程

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

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

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

0c1195f0cbbba8adac6482df8b6c1df3.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, 我们可以看到如下文档标题已经生成。

a94cb3277734accff4c0bd273d745a5a.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, 运行一下。

9fc54cda27289cca8cebadddbab5b881.png

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

9d0c35f65e53e2df56a5ee4aefd5e092.png

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

3eecd2eb6977ccc562a881871b805a92.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

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/news/531866.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

android执行main函数,AndroidStudio执行main方法报错

android执行main函数,AndroidStudio执行main方法报错

问题：有时在开发中想直接写一个java文件来测试一些东西，但是AndroidStudio执行的时候会报错。代码信息：public class HelloWorld {public static void main(String[] args) {System.out.println("HelloWorld");}}报错信息12:04:41:…
阅读更多...
hive 导出json格式 文件_Hive 系列 之 基本操作合集

hive 导出json格式 文件_Hive 系列 之 基本操作合集

下面是本课程概览：（1）hive系列之简介，安装，beeline和hiveserver2（2）hive系列之基本操作（3）hive系列之udf（4）hive系列之二级分区和动态分区&#x…
阅读更多...
android开发自定义view倍丝曲线,从0到1Android自定义View（四）贝塞尔曲线

android开发自定义view倍丝曲线,从0到1Android自定义View（四）贝塞尔曲线

原标题：从0到1Android自定义View(四)贝塞尔曲线2017年安卓巴士全球开发者论坛-上海站作者本文由两点水投稿，博客地址：http://www.apkbus.com/myspaceblog-911082.html前言扯来扯去，前面三篇自定义 View 文章，终于扯完了…
阅读更多...
ios kvo 要引入_腾讯社招iOS面试记录

ios kvo 要引入_腾讯社招iOS面试记录

毕业好几年了，上周发送了简历给腾讯，参加了腾讯面试。具体部门这边就不说了。这次面试还是收获到了很多。一面电话面试：面试官主要是针对iOS相关的基础问题。先简单自我介绍一下自己对mrc和arc的理解谈谈对自动释放池的理解自动释放池在mrc和…
阅读更多...
html 中加号的表示方法,CSS的+(加号)选择器怎么用

html 中加号的表示方法,CSS的+(加号)选择器怎么用

在CSS中“”符号选择器用于选择紧跟在指定元素之后但不在特定元素内部的元素。下面本篇文章就来具体介绍一下，希望对大家有所帮助。“”符号选择器在CSS中“”符号选择器被称为相邻兄弟选择器，用于选取在同一父元素下的，紧跟指定元素之后的另…
阅读更多...
华为新系统 鸿蒙,旗舰CPU＋鸿蒙OS！华为Mate家族重磅新品来袭

华为新系统 鸿蒙,旗舰CPU＋鸿蒙OS！华为Mate家族重磅新品来袭

我们常说安卓平板的生态跟苹果iPad有很大差距，不论是应用质量还是原生系统支持，苹果都做的更好一些。可能也是因为这个原因，因此安卓平板，尤其是旗舰级别的平板至今除了三星之外，也就只有华为在做。作为安卓阵营两大厂…
阅读更多...
mysql中用来取余数的函数是_MySQL常用函数-单行处理函数-字符串处理函数(更新中...)...

mysql中用来取余数的函数是_MySQL常用函数-单行处理函数-字符串处理函数(更新中...)...

本篇文章用到的数据库表/* SQLyog Ultimate v12.09 (64 bit) MySQL - 5.7.23-log : Database - myemployees ********************************************************************* *//*!40101 SET NAMES utf8 */;/*!40101 SET SQL_MODE*/;/*!40014 SET OLD_UNIQUE_CHECKSUN…
阅读更多...
html盒子模型页面居中,【静态页面架构】CSS之盒子模型

html盒子模型页面居中,【静态页面架构】CSS之盒子模型

CSS架构盒子模型；以内容区(显示文本和图像)内边距(内容区至边距的距离)边距(内容区的边界)外边距(元素的边框之间的距离)1.边距；border属性；简写属性用来设置边距的上(top)右(right)下(bottom)左(left)。宽度，颜色和样式div{width…
阅读更多...
最强动画制作人书包_声优访谈丨恋与制作人动画中配声优访谈——夏磊

最强动画制作人书包_声优访谈丨恋与制作人动画中配声优访谈——夏磊

亲爱的制作人们：距离恋与制作人动画上线还有6天！今天的中配声优访谈嘉宾是在动画中为许墨献声的夏磊老师~固定布局 工具条上设置固定宽高背景可以设置被包含可以完美对齐背景图和文字以及制作自…
阅读更多...
codesys com库_CoDeSys官方系统库在线下载，替换国内下载服务器教程

codesys com库_CoDeSys官方系统库在线下载，替换国内下载服务器教程

欢迎加入工控分享技术服务社区推荐阅读Codesys学习资料大全Codesys控制器关于CANopen总线的详细应用说明当你软件报以下错误，你可以直接下载，如果下载不成功，可以换个网络试一试，或者进行下面的操作。由于国内网络问题&#xff0c…
阅读更多...
centos7恢复mysql数据库_MySQL数据库升级迁移填坑记

centos7恢复mysql数据库_MySQL数据库升级迁移填坑记

原库：*.*.101.73/74 系统环境: Suse 12.4MySQL: 5.7.29新库：*.*.110.46/47系统环境：CentOS7.7 64位MySQL版本: 5.7.30[一、数据库升级迁移场景]因业务侧在*.*.101.73/74 mysql数据库服务器上部署了java应用程序、HadoopHbase数据库等大数据…
阅读更多...
so把asp页面生成静态的html,23、asp系列课程--server.URLEncode方法和server.HTMLEncode方法...

so把asp页面生成静态的html,23、asp系列课程--server.URLEncode方法和server.HTMLEncode方法...

作者：杨凡来自：杨凡博客地址：blog.sina.com.cn/aboutshisanserver.URLEncode方法和server.HTMLEncode方法可以对字符串进行编码。我们一个一个的说。server.URLEncode可以对字符串进行URL编码转换，语法格式为：server.u…
阅读更多...
下列关于html5表单的多样输入方式,IT兄弟连 HTML5教程 HTML5表单 多样的输入类型1...

下列关于html5表单的多样输入方式,IT兄弟连 HTML5教程 HTML5表单 多样的输入类型1...

原标题：IT兄弟连 HTML5教程 HTML5表单 多样的输入类型1HTML5拥有多个新的表单输入类型，这些新特性提供了更好的输入控制和验证。并不是所有的主浏览器都支持新的input类型，不过我们可以在所有的主浏览器中使用它们，即使不被支持&a…
阅读更多...
v7000更换电池步骤_ups电源运行中是否可以更换电池?应如何操作呢

v7000更换电池步骤_ups电源运行中是否可以更换电池?应如何操作呢

ups电源在日常使用中除了日常维护工作之外，对于使用达到一定年限的时候，内部使用的ups蓄电池就需要更换了，很多人以为ups不间段电源在工作的时候是可以跟换电池。其实，这个具体就需要看ups电源设计的原理，不同厂家设计…
阅读更多...
华为怎么用手机看时间到读秒_华为手机灭屏也可以看时间？其实设置方法很简单，不会有些可惜了...

华为怎么用手机看时间到读秒_华为手机灭屏也可以看时间？其实设置方法很简单，不会有些可惜了...

华为作为手机界名副其实的大佬，而且华为手机的口碑也是非常不错的。那么为什么会有这么多人喜欢华为手机呢？主要是华为手机的质量高，并且用很多实用的小功能，比如说神奇的灭屏显示功能等等，今天就给大家分享几个华为手…
阅读更多...
hive转16进制unhex_Java 进制的转换

hive转16进制unhex_Java 进制的转换

什么是进制？进制也就是进位计数制，是人为定义的带进位的计数方法(有不带进位的计数方法，比如原始的结绳计数法，唱票时常用的“正”字计数法，以及类似的tally mark计数)。 对于任何一种进制---X进制，就表示每…
阅读更多...
引入ui组件_Vuejs, Semantic CSS前端框架fish-ui

引入ui组件_Vuejs, Semantic CSS前端框架fish-ui

简介基于vue2.0, github star 690, 一款小众的UI框架fish-ui，直接上截图：主要特性配备Vue.js，Moment，Vue-Router，ES6和Babel 6使用Webpack 2.0和Vue LoaderSemantic CSS 组件使用 Less支持现代浏览器快速开发安装npm i…
阅读更多...
减去字符串_从文本字符串中提取指定值的6个超级技巧解读

减去字符串_从文本字符串中提取指定值的6个超级技巧解读

在实际的工作中，从指定的字符串中提取指定文本也是常用的技巧之一，除了手动操作之外，下文的8种应用技巧也是必须要掌握的。一、Left函数法。功能：从指定文本字符串的第一个字符开始，提取指定长度的字符串。语法结构&am…
阅读更多...
如果用计算机录制歌曲需要,网络歌手怎么用电脑录音软件录歌

如果用计算机录制歌曲需要,网络歌手怎么用电脑录音软件录歌

现在网上有很多网络歌手主要分为两类，一类是原创，一类是翻唱。可是不管是原创还是翻唱都需要自己唱歌录歌，要有属于自己的歌曲(自己唱的)。要录歌就要有设备，毕竟网路歌手刚开始大多数都是草根没有钱找音乐工作室，只能…
阅读更多...
中国剩余定理证明过程

中国剩余定理证明过程

原网址：http://blog.csdn.net/wtq493841534/article/details/5452720 中国剩余定理 中国剩余定理可以描述为： 若某数x分别被d1、、…、dn除得的余数为r1、r2、…、rn，则可表示为下式：xR1r1R2r2…RnrnRD其中R1是d2、d3、…、dn的公…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023