swaggo 简记

这是我参与「第五届青训营 」伴学笔记创作活动的第 8 天 如果说go比java好的地方，那么好就好在简单，不用那么多繁文缛节，但坏也坏在这个地方。在后端开发是，Java的swagger文档可以直接用注解来写，而go一般则是使用swaggo这个生成工具，通过解析注释的方式，说实话挺难用的。 举个简单的例子，比如我们要定义一个API接口，获取用户信息。

// @Summary 获取用户信息
// @Description 根据用户ID获取用户信息
// @Tags User
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} User
// @Failure 404 {object} ErrorResponse
// @Router /user/{id} [get]
func GetUser(c echo.Context) {
    // 获取用户信息的实现逻辑
}

我们使用了一系列以“@”符号开头的注释，这些注释中包含了接口的各种信息，如接口名称、描述、请求方式、请求参数、响应结果等。这些注释会被swaggo解析，然后生成相应的API文档。

然而这些@开头的句子和go没有半毛钱关系。这些注释是swaggo自己定义的一套语法。

实际上写起来那是相当痛苦，没有IDE提示，一不小心就容易写错。要等运行生成器的时候才能发现错误，而且错误信息也不是很友好。 像上面这个例子，请求参数需要使用 @Param id path int true "用户ID"的格式，其中id是参数名，path是参数类型，int是参数数据类型，true是是否必须，最后是参数描述。如果是query部分，那么就是@Param id query int true "用户ID"，其他类型以此类推。 如果不小心记错了顺序，参数又多那么几个，就麻烦咯。

幸好这个库大发慈悲，还给了我们一些简化参数书写的方法，那就是直接使用具体的go struct类型，然后swaggo 会自动解析这个struct的字段，然后生成文档，包括参数名、参数类型、参数描述等。 举一个具体的例子，假设有一种请求参数的结构体如下：

type UserReq struct {
    ID   int    `json:"id" form:"id" query:"id"` // 用户ID
    Name string `json:"name" form:"name" query:"name"` // 用户名
}

那么我们可以这样写注释：

// @Summary 获取用户信息
// @Description 根据用户ID获取用户信息
// @Tags User
// @Accept json
// @Produce json
// @Param user body UserReq true "用户信息"
// @Success 200 {object} User
// @Failure 404 {object} ErrorResponse
// @Router /user [get]
func GetUser(c echo.Context) {
    // 获取用户信息的实现逻辑
}

这样就可以省去很多麻烦了。但其实每当使用各种语言的类似结构体一样的东西会出现一个新的问题，参数命名风格，驼峰式命名和下划线命名之类的问题。 还好生成器也提供了这个工具。