Swagger、API 规范和代码生成

Woodpecker 使用 gin-swagger 中间件从源代码自动生成 Swagger v2 API 规范和美观的 Web UI。 此外，生成的规范将使用 go-swagger 转换为 Markdown，然后在社区网站文档中使用。

保持 gin 处理函数的 godoc 文档最新至关重要，以始终拥有准确的 API 文档。 每当您更改、添加或增强 API 端点时，请更新 godoc。

您的机器上不需要任何额外的工具，所有 Swagger 工具都会被标准 Go 工具自动获取。

Gin-Handler API 文档指南

这是 Swagger 文档注释的典型示例...

server/api/user.go

// @Summary  Get a user
// @Description Returns a user with the specified login name. Requires admin rights.
// @Router   /users/{login} [get]
// @Produce  json
// @Success  200 {object} User
// @Tags   Users
// @Param   Authorization header string true "Insert your personal access token" default(Bearer <personal access token>)
// @Param   login   path string true "the user's login name"
// @Param   foobar  query   string false "optional foobar parameter"
// @Param   page    query int  false "for response pagination, page offset number" default(1)
// @Param   perPage query int  false "for response pagination, max items per page" default(50)

server/model/user.go

type User struct {
  ID int64 `json:"id" xorm:"pk autoincr 'user_id'"`
// ...
} // @name User

这些指南旨在在 OpenAPI 文档中保持一致的措辞：

• @Summary 和 @Description 后的第一个单词始终大写
• @Summary 在行末没有 .（点）
• 模型结构体应使用自定义短名称，使用 @name 为 API 消费者提供便利
• @Success 对象或数组声明应简短，这意味着实际的 model.User 结构体必须有 @name 注释，以便模型可以在 OpenAPI 中呈现
• 使用分页时，必须手动添加 @Param page 和 @Param perPage
• @Param Authorization 几乎总是存在，只有少数未受保护的端点

在 server/api 包中有许多示例，您可以将其用作蓝图。 更多详细信息可以在这里找到 https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format

手动代码生成

生成包含 OpenAPI 的服务器 Go 代码

make generate-openapi

更新 ./docs 文件夹中的 Markdown

make generate-docs