近年来，随着互联网技术的不断发展，web api接口的重要性越来越高，而编写api文档也成为了开发工作中重要的一环。在go语言中，我们可以使用openapi/swagger进行api文档编写。
OpenAPI/Swagger是一种API规范和工具链，可以帮助我们构建和描述符合RESTful架构风格的API接口。它包含了一套规范的API描述语言和一系列的工具，可以帮助我们自动生成API文档、客户端代码和服务端框架。
在Go语言中，可以使用Swagger的Go官方实现“swag”来快速生成API文档。下面我们将学习如何使用swag编写API文档。
首先，我们需要在项目中添加swag，可以使用如下命令将它加入到项目中：
go get -u github.com/swaggo/swag/cmd/swag
安装完swag之后，我们需要在main.go文件中导入swag相关的包：
立即学习“go语言免费学习笔记（深入）”；
import (
"github.com/swaggo/files"
"github.com/swaggo/gin-swagger"
"github.com/gin-gonic/gin"
)
// 注册swag
func setUpSwagger(engine *gin.Engine) {
engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}
func main() {
// 初始化 gin 引擎
engine := gin.Default()
setUpSwagger(engine)
router.LoadRouters(engine)
_ = engine.Run()
}接下来，我们可以在接口注释中使用swagger注释对接口进行描述。例如：
本文档主要讲述的是Android中JNI编程的那些事儿；JNI译为Java本地接口。它允许Java代码和其他语言编写的代码进行交互。在android中提供JNI的方式，让Java程序可以调用C语言程序。android中很多Java类都具有native接口，这些接口由本地实现，然后注册到系统中。希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看
// User register router
// @Summary User register router
// @Description User register router
// @Tags Users
// @Accept json
// @Produce json
// @Param user_in body models.NewUser true "user info"
// @Success 200 {string} json "{"code":200,"data":null,"msg":"Register successful"}"
// @Failure 400 {string} json "{"code":400,"msg":"Bad Request"}"
// @Router /users/register [post]
func Register(c *gin.Context) {
name := c.PostForm("name")
password := c.PostForm("password")
...
}在注释中，我们使用了一些swagger的注解：
- @Summary: 接口概要信息
- @Description: 接口详细描述
- @Tags: 接口所属标签
- @Accept: 接口请求Content-Type
- @Produce: 接口响应Content-Type
- @Param: 接口参数描述，包括参数位置、参数名、是否为必选参数、参数描述和参数示例
- @Success: 接口成功响应描述，可以包括响应Code、响应信息和响应数据结构
- @Failure: 接口失败响应描述，同样可以包括响应Code和响应信息
最后，我们需要在项目根目录下使用swag init命令生成API文档，文档会生成在docs目录下。
swag init
现在，我们就可以通过访问http://localhost:8080/swagger/index.html 来查看API文档了。
总的来说，使用OpenAPI/Swagger编写API文档可以帮助我们更加清晰地描述接口，容易阅读和理解。而Go语言的swag库可以快速生成API文档，使我们更加高效地进行开发。
