使用 Go 添加文档 - Golang教程网

简介

对于 API 服务来说, 文档是必不可少的.

然而文档却挺烦人的, 尤其是同步更新的问题. 如果选择手写文档, 经常会忘了更新文档; 或者处于高速开发的前期, 来不及更新文档.

文档即注释

文档即测试

这就是 swagger.

swagger 起步

swagger 提供了很多工具用于创建 API 文档, 尤其是创建了 RESTful APIs 标准.

OpenAPI Specification2.03.02.0

2.0

安装 swag 工具, 也可以直接下载预编译的二进制文件.

go get -u github.com/swaggo/swag/cmd/swag
复制代码

swag init

swag init
复制代码

swag-gin

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
复制代码

到这里, 依赖已经安装完成了, 剩下的就是编写文档了.

编写文档

毕竟是一种规范, 还是要学习它的使用方式的, 如果有兴趣, 可以看原始的规范.

这里看 swag 库的文档就行了, Declarative Comments Format.

@key value

main

// @title Apiserver API
// @version 1.0
// @description This is a simple api server.

// @contact.name coolcat
// @contact.url http://coolcat.io/support
// @contact.email help@coolcat.io

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

// @host 127.0.0.1:8081
// @BasePath /v1

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
func main() {
	cmd.Execute()
}
复制代码

在上面的注释里, 主要有四部分, 分别定义了:

标题, 版本号, 描述
联系信息
license
安全定义

router.go

import {
  swaggerFiles "github.com/swaggo/files"
  ginSwagger "github.com/swaggo/gin-swagger"
    // docs is generated by Swag CLI, you have to import it.
  _ "tzh.com/web/docs"
}

func Load(g *gin.Engine, mw ...gin.HandlerFunc) *gin.Engine {
  ...
  // swagger 文档
	// The url pointing to API definition
	// /swagger/index.html
	url := ginSwagger.URL("/swagger/doc.json")
	g.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
  ...
}
复制代码

剩下的就是编写每个接口的文档了, 举个例子, login 接口的文档如下:

// @Summary 登录
// @Description 登录账户, 获取 token
// @Tags login
// @Accept  json
// @Produce  json
// @Param body body model.UserModel true "User login""
// @Success 200 {object} model.Token "{"code":0,"message":"OK","data":{"token":"name"}}"
// @Router /login [post]
func Login(ctx *gin.Context) {
复制代码

这里定义了接口的基本属性, 包括路径, 请求类型, 成功时的输出, 输出格式等.

// @Summary 获取用户
// @Description 从数据库中获取用户信息
// @Tags user
// @Accept  json
// @Produce  json
// @Security ApiKeyAuth
// @Param id path uint64 true "user id in database"
// @Success 200 {object} model.UserModel "{"code":0,"message":"OK","data": {}}"
// @Router /user/{id} [get]
func Get(ctx *gin.Context) {
复制代码

@Security ApiKeyAuthmainApiKeyAuth

swag init

/swagger/index.html

更多的文档注释, 可以在源代码中查看.

运行

swag init

build: updoc
	go build -ldflags ${ldflags} ./
run: updoc
	go run -ldflags ${ldflags} ./
docker: updoc
	go run -ldflags ${ldflags} ./ -c ./conf/config_docker.yaml
updoc:
	go mod download
	go get -u github.com/swaggo/swag/cmd/swag
	swag init
复制代码

make runhttp://localhost:8081/swagger/index.htmlhttp://localhost:8081/swagger/doc.json

总结

swagger 为文档的编写提供了极大的便利, 工具虽好, 更重要的是坚持.

当前部分的代码

作为版本 v0.16.0