Go语言使用swagger生成接口文档的方法

公司使用Golang的iris框架进行开发,同时使用了swagger为代码自动生成接口文档

本篇为Go语言使用swagger生成接口文档的方法记录,代码中注释什么的放在文中详细介绍,这里主要说一下生成文档数据的命令。

编写完注释后,使用以下命令安装swag工具:go get -u github.com/swaggo/swag/cmd/swag

在项目根目录执行以下命令,使用swag工具生成接口文档数据:swag init

执行完上述命令后,如果你写的注释格式没问题,此时你的项目根目录下会多出一个docs文件夹。

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

API 文档截图

Go语言使用swagger生成接口文档的方法插图

swagger介绍

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用,以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档,代码生成和测试用例生成。

在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力。

最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新,而Swagger正是那种能帮我们解决接口文档问题的工具。

golang的swagger注解

@Tags: 分类信息
例如:

// @Tags 用户接口
Go语言使用swagger生成接口文档的方法插图1

@Summary: 操作的简短摘要。
例如:

[email protected] 通过用户名得到用户信息
Go语言使用swagger生成接口文档的方法插图2

@Description: 操作的详细说明。
例如:

[email protected] 操作行为的详细说明。
Go语言使用swagger生成接口文档的方法插图3

@Param:参数信息,用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)
1.参数名
2.参数类型,可以有的值是 formData、query、path、body、header,formData 表示是 post 请求的数据,query 表示带在 url 之后的参数,path 表示请求路径上得参数,例如上面例子里面的 key,body 表示是一个 raw 数据请求,header 表示带在 header 信息中得参数。
3.参数类型
4.是否必须
5.注释
例如:

// @Param name query string true "用户姓名"
Go语言使用swagger生成接口文档的方法插图4

发表评论

后才能评论