mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-11-27 04:11:03 +00:00
64 lines
2.8 KiB
Markdown
64 lines
2.8 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...
|
||
|
|
|
||
|
|
```go title="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)
|
||
|
|
```
|
||
|
|
|
||
|
|
```go title="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/main/README.md#declarative-comments-format>
|
||
|
|
|
||
|
|
### Manual code generation
|
||
|
|
|
||
|
|
```bash title="generate the server's Go code containing the Swagger"
|
||
|
|
make generate-swagger
|
||
|
|
```
|
||
|
|
|
||
|
|
```bash title="update the Markdown in the ./docs folder"
|
||
|
|
make docs
|
||
|
|
```
|
||
|
|
|
||
|
|
```bash title="auto-format swagger related godoc"
|
||
|
|
go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go
|
||
|
|
```
|