0x01 安装
- 首先下载swag程序
go get -u github.com/swaggo/swag/cmd/swag - 编译完成之后，使用项目根目录命令初始化项目
swag init
0x02 文档编写
项目概要编写
// @title HIDS MIS API
// @version 1.0
// @description 这是HIDS web 控制端API
// @contact.name u1timate
// @contact.email u1timate
// @BasePath /v1
func Server(){}
普通请求注释说明
POST请求
//CommandSearch 获取历史命令列表
// @Tags 命令接口
// @Produce json
// @version 1.0
// @Accept application/json
// @Description 获取历史命令列表
// @Router /command/search [post]
// @Success 200 {object} cmdSearchResponse
// @Failure 400 {string} json "{"code": 400,"data": "","msg": "失败"}"
// @Param default body cmdSearchRequest true "请求参数"
带Param参数的请求
//PluginTemplate 获取插件配置的模板
// @Tags 插件接口
// @Produce json
// @version 1.0
// @Accept application/json
// @Description 获取插件配置的模板
// @Router /plugin/template/{type} [post]
// @Success 200 {string} json "{"code": 200,"data": "","msg": ""}"
// @Failure 400 {string} json "{"code": 400,"data": "","msg": ""}"
// @Param default body pluginTemplateRequest true "请求参数"
// @Param type path string true "config or command"
- Param type
- query
- path
- header
- body
- formData
- data type
- string (string)
- integer (int, uint, uint32, uint64)
- number (float32)
- boolean (bool)
- user defined struct
Param指令
主要是对请求数据包进行解释说明
@Param default body cmdSearchRequest true "请求参数"
格式为：param name,param type,data type,is mandatory(是否为必须的)?,comment attribute(optional)
参数名称如果是post请求，这可以是使用default
如果是通过url path参数传递数据，这表示方式为
// @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]
Success指令
主要是对返回数据包进行解释说明
//@Success return code or default, {param type}, data type, comment
举例
@Success 200 {array} model.Account <-- This is a user defined struct.
//// JSONResult's data field will be overridden by the specific type proto.Order
@success 200 {object} jsonresult.JSONResult{data=[]proto.Order} "desc"
0x03 Gin中调用
下载第三方包
go get -u github.com/swaggo/gin-swagger
import (
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
"hids_web/docs"
)
//一定要放在main.go里面
// @title HIDS MIS API
// @version 1.0
// @description 这是HIDS web 控制端API
// @contact.name u1timate
// @contact.email u1timate
// @BasePath /v1
func main(){
router := gin.Default()
url := ginSwagger.URL("http://"+addr+"/swagger/doc.json") // The url pointing to API definition ，注意这里的addr不能使用0.0.0.0，
//支持人工指定相关接口信息
docs.SwaggerInfo.Title = "HIDS MIS API"
docs.SwaggerInfo.Description = "这是HIDS web 控制端API"
docs.SwaggerInfo.Version = "2.0"
docs.SwaggerInfo.BasePath = "/v1"
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url)) // Register on http://localhost:8080/swagger
}
每次修改描述信息后命令上使用Swag init
如果出现某些结构体无法解析识别，可使用命令
~/go/bin/swag init --parseInternal --parseDependency
完成之后，启动服务器，即可通过浏览器访问，如果在上述代码url := ginSwagger.URL("http://"+addr+"/swagger/doc.json")
addr指的的地址为127.0.0.1，那么则可通过访问http://127.0.0.1/swagger/index.html访问接口文档