woodpecker/docs/docs/92-development/08-swagger.md

Swagger, API Spec and Code Generation

Woodpecker uses gin-swagger middleware to automatically generate Swagger v2 API specifications and a nice looking Web UI from the source code. Also, the generated spec will be transformed into Markdown, using go-swagger and then being using on the community's website documentation.

It's paramount important to keep the gin handler function's godoc documentation up-to-date, to always have accurate API documentation. Whenever you change, add or enhance an API endpoint, please update the godocs.

You don't require any extra tools on your machine, all Swagger tooling is automatically fetched by standard Go tools.

Gin-Handler API documentation guideline

Here's a typical example of how annotations for Swagger documentation look like...

--- 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

These guidelines aim to have consistent wording in the swagger doc:

• first word after @Summary and @Summary are always uppercase
• @Summary has no . (dot) at the end of the line
• model structs shall use custom short names, to ease life for API consumers, using @name
• @Success object or array declarations shall be short, this means the actual model.User struct must have a @name annotation, so that the model can be renderend in Swagger
• when pagination is used, @Parame page and @Parame perPage must be added manually
• @Param Authorization is almost always present, there are just a few un-protected endpoints

There are many examples in the server/api package, which you can use a blueprint. More enhanced information you can find here https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format

Manual code generation

generate the server's Go code containing the Swagger

make generate-swagger

update the Markdown in the ./docs folder

make docs

auto-format swagger related godoc

go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go

WARNING, known issue: using swag v1.18.12 , there's a bug when running the fmt command, which makes the swagger generator failing, because it can't find the models/structs/types anymore. To fix it, please replace // @name\tModelName with // @name ModelName, which means, replace the tab (\t) with a space ( ). See https://github.com/swaggo/swag/pull/1594 == once this is merged and released, the mentioned issue is obsolete.