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 后面的第一个单词和 @Summary 始终大写
@Summary 行末没有 .（点）
模型结构体应该使用自定义短名称，以方便 API 使用者，使用 @name
@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

Gin-Handler API 文档指南​

手动代码生成​

Gin-Handler API 文档指南

手动代码生成