mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-12-15 21:16:32 +00:00
77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
|
# Swagger, API Spec and Code Generation
|
||
|
|
|
||
|
|
Woodpecker uses [gin-swagger](https://github.com/swaggo/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](https://github.com/go-swagger/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...
|
||
|
|
|
||
|
|
```text
|
||
|
|
--- 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)
|
||
|
|
```
|
||
|
|
|
||
|
|
```text
|
||
|
|
--- 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
|
||
|
|
|
||
|
|
```shell
|
||
|
|
make generate-swagger
|
||
|
|
```
|
||
|
|
|
||
|
|
##### update the Markdown in the ./docs folder
|
||
|
|
|
||
|
|
```shell
|
||
|
|
make docs
|
||
|
|
```
|
||
|
|
|
||
|
|
##### auto-format swagger related godoc
|
||
|
|
|
||
|
|
```shell
|
||
|
|
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.
|