Hertx-swag

swag可以集成在多个web框架中，一键生成api文档，可以让你更加专注于业务逻辑，更加专注于开发。另外通过swagger插件可以使文档在线运行并调用接口，兼顾部分测试api接口的功能。

本文主要介绍如何在hertx中使用swagger，并以案例的形式阐述各个api注释的作用，并实现远程调用访问swagger。

效果图：

特性

• 自动生成api文档
• 支持多种web框架
• 在线生成api接口并能在线调用

官方文档

快速开始

1. 安装

## 安装到gopath中，其它项目也可以使用swag插件
go install github.com/swaggo/swag/cmd/swag@latest

# 仅在本项目安装
go get github.com/swaggo/swag/cmd/swag

2. 编写api注释

• 通用注释

通用注释就是介绍swagger信息，项目信息，协议，外连接等。如下所示：

注释如下：

// @title Hertz-swag
// @version 1.0
// @description This is a demo using Hertz-swag.

// @contact.name hertz-contrib
// @contact.url https://github.com/hertz-contrib

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8888
// @BasePath /
// @schemes http

那么从上到下依次是：

上面只是一部分，实际还有很多，具体可以参考官方文档:API General Info 一般情况下，只要一个title,version,lisence.name && url,schemes就可以了，如下：

• 路由注释

路由注释就是介绍接口信息，请求方式，请求路径，请求参数，响应参数，响应状态码等。如下图所示：

实际上并不需要这么多，通过实践来看一般需要Summary,Description,Tags,Param,Success,Failure,Router即可。

上面只是一部分，实际还有很多，具体可以参考官方文档:swagger

如下所示的注释和生成的在线文档：

// Showregister godoc
//  @Id 1
//	@Summary		get a new account
//	@Description	register user
//	@Tags			user
//	@Accept			json
//	@Produce		json
//	@Param          user body user.User true "user info"
//	@Success		200	{object}	user.User
//	@Failure		400	{object}	utool.HTTPError
//	@Router			/user/register [POST]
func RegisterUser(ctx context.Context, c *app.RequestContext) {
    var err error
    var req user.User
    err = c.BindAndValidate(&req)
    if err != nil {
        c.String(consts.StatusBadRequest, err.Error())
        return
    }
    resp := new(user.User)
    c.JSON(consts.StatusOK, resp)
}

展开如下：

显然@Param,@Success,@Failure,@Router是最重要的注释，其他的都是辅助注释。

注意：

1. @Param注释中，type字段是必填项，name字段是必填项，description字段是必填项，required字段是可选项，default字段是可选项。
2. @Success和@Failure注释中，code字段是必填项，其后都是{object} 响应参数的json格式,后面跟着响应参数的类型，如{object} user.User，这个user.User是我们定义的结构体。
3. @Router注释中，path字段是必填项，method字段是必填项`，path填理由，method填请求方法。

@Param [请求变量名] [HTTP请求类型] [请求参数类型] [是否必填 true false] [请求参数说明]

• 请求变量名自定义，一般要求和方法参数一样

• 请求参数类型

• 是否必填

是否必填，true表示必填，false表示非必填，默认是false。

• 请求参数说明

请求参数说明，一般是参数的作用，如@Param user body user.User true "user info"，表示请求参数为user类型，参数为user.User结构体，必填，参数说明为user info。

注意：

1. 一般情况下，@Param注释中，type字段是必填项，也就是HTTP请求必填`
2. 更多请看官网swag

• 响应参数类型

• 响应状态码

注意：

1. 一般情况下，@Success和@Failure注释中，code字段是必填项，也就是HTTP响应状态码

• 返回实参类型

与响应参数类型对应即可

• 响应参数说明

略

3. 生成api文档

确保已经安装了swag插件，编写完注释后，执行如下命令即可生成api文档：

swag init

注意：

1. 确保在更目录下，项目中需要有main函数。

执行完命令后，会在当前目录下生成docs目录，如下文件：

docs目录结构如下： )

├── docs
│   ├── docs.go
│   ├── swagger.yaml
│   ├── swagger.json

• docs.go

docs.go是自动生成的，主要是用于生成swagger文档的，可以忽略。

4. 访问api文档

• 安装 hertz-swagger

go get github.com/hertz-contrib/swagger
go get github.com/swaggo/files

• 在主路由中引入hertz-swagger和docs

import "github.com/hertz-contrib/swagger" // hertz-swagger middleware
import "github.com/swaggo/files" // swagger embed files
import _ "userservice/docs"  //docs没有实际引用但是需要使用json文件

• 配置swagger路由

url := swagger.URL("http://192.168.5.167:8081/swagger/doc.json") // The url pointing to API definition
h.GET("/swagger/*any",swagger.WrapHandler(swaggerFiles.Handler, url))

注意：

1. swagger.URL("http://192.168.5.167:8081/swagger/doc.json") 中swagger.URL是"github.com/hertz-contrib/swagger"库的方法,
2. swagger.WrapHandler(swaggerFiles.Handler, url)不用改动
3. h是*Hertz对象。

• 访问api文档

访问http://localhost:8080/swagger/index.html即可看到api文档。

注意：

1. localhost是本地极大值，局域网中需要换为ip地址。
2. 如果在局域网被其他人访问,hertx服务器需要启动在0.0.0.0地址上,如：h := server.New(server.WithHostPorts("0.0.0.0:8081"))
3. 访问http://localhost:8080/swagger/doc.json可以看到json格式的文档。

5. 总结

通过swag插件，可以自动生成api文档，并且可以访问api文档。

注意：

1. 注意@Param注释中，type字段是必填项，name字段是必填项，description字段是必填项，required字段是可选项，

5. 注意事项

1. 局域网访问需要注意跨域问题，需要在hertz服务器启动时指定0.0.0.0地址，如：h := server.New(server.WithHostPorts("0.0.0.0:8081"))。
2. swagger.URL()需要指定为本地ip，不能是localhost和127.0.0.1
3. 需要在响应头中设置Access-Control-Allow-Origin: *，或者添加放行的ip地址，不然会有cors跨域问题。
4. 在使用cors中间件时有两种方式一种直接在路由加，另一种使用cors库加，使用第一种是中间件要在swagger.WrapHandler()之前不然无效。

)