Update swagger API specification (#1782)

# Summary

This PR drops the outdated former swagger.yaml/json and introduced
automatic API document generation from Go code.
The generated code is also used to generate documentation/markdown for
the community page,
as well as enable the Woodpecker server to serve a Swagger Web UI for
manual tinkering.

I did opt-in for gin-swagger, a middleware for the Gin framework, to
ease implementation and have a sophisticated output.
This middleware only produces Swagger v2 specs. AFAIK the newer OpenApi
3x tooling is not yet that mature,
so I guess that's fine for now.

## Implemenation notes

- former swagger.json files removed
- former // swagger godocs removed
- introduced new dependency gin-swagger, which uses godoc annotations on
top of Gin Handler functions.
- reworked Makefile to automatically generate Go code for the server
- introduce new dependency go-swagger, to generate Markdown for
documentation purposes
- add a Swagger Web UI, incl. capabilities for manual API exploration
- consider relative root paths in the implementation
- write documentation for all exposed API endpoints
- incl. API docs in the community website (auto-generated)
- provide developer documentation, for the Woodpecker authors
- no other existing logic/code was intentionally changed

---------

close #292

---------

Co-authored-by: qwerty287 <80460567+qwerty287@users.noreply.github.com>
Co-authored-by: 6543 <6543@obermui.de>

server/api/cron.go

@@ -28,8 +28,17 @@ import (
 	"github.com/woodpecker-ci/woodpecker/server/store"
 )
 
-// GetCron gets a cron job by id from the database and writes
-// to the response in json format.
+// GetCron
+//
+//	@Summary	Get a cron job by id
+//	@Router		/repos/{owner}/{name}/cron/{cron} [get]
+//	@Produce	json
+//	@Success	200	{object}	Cron
+//	@Tags		Repository cron jobs
+//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		owner			path	string	true	"the repository owner's name"
+//	@Param		name			path	string	true	"the repository name"
+//	@Param		cron			path	string	true	"the cron job id"
 func GetCron(c *gin.Context) {
 	repo := session.Repo(c)
 	id, err := strconv.ParseInt(c.Param("cron"), 10, 64)
@@ -46,7 +55,17 @@ func GetCron(c *gin.Context) {
 	c.JSON(http.StatusOK, cron)
 }
 
-// RunCron starts a cron job now.
+// RunCron
+//
+//	@Summary	Start a cron job now
+//	@Router		/repos/{owner}/{name}/cron/{cron} [post]
+//	@Produce	json
+//	@Success	200	{object}	Pipeline
+//	@Tags		Repository cron jobs
+//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		owner			path	string	true	"the repository owner's name"
+//	@Param		name			path	string	true	"the repository name"
+//	@Param		cron			path	string	true	"the cron job id"
 func RunCron(c *gin.Context) {
 	repo := session.Repo(c)
 	_store := store.FromContext(c)
@@ -77,7 +96,17 @@ func RunCron(c *gin.Context) {
 	c.JSON(http.StatusOK, pl)
 }
 
-// PostCron persists the cron job to the database.
+// PostCron
+//
+//	@Summary	Persist/creat a cron job
+//	@Router		/repos/{owner}/{name}/cron [post]
+//	@Produce	json
+//	@Success	200	{object}	Cron
+//	@Tags		Repository cron jobs
+//	@Param		Authorization	header	string		true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		owner			path	string		true	"the repository owner's name"
+//	@Param		name			path	string		true	"the repository name"
+//	@Param		cronJob			body	Cron	true	"the new cron job"
 func PostCron(c *gin.Context) {
 	repo := session.Repo(c)
 	user := session.User(c)
@@ -124,7 +153,18 @@ func PostCron(c *gin.Context) {
 	c.JSON(http.StatusOK, cron)
 }
 
-// PatchCron updates the cron job in the database.
+// PatchCron
+//
+//	@Summary	Update a cron job
+//	@Router		/repos/{owner}/{name}/cron/{cron} [patch]
+//	@Produce	json
+//	@Success	200	{object}	Cron
+//	@Tags		Repository cron jobs
+//	@Param		Authorization	header	string		true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		owner			path	string		true	"the repository owner's name"
+//	@Param		name			path	string		true	"the repository name"
+//	@Param		cron			path	string		true	"the cron job id"
+//	@Param		cronJob			body	Cron	true	"the cron job data"
 func PatchCron(c *gin.Context) {
 	repo := session.Repo(c)
 	user := session.User(c)
@@ -183,8 +223,18 @@ func PatchCron(c *gin.Context) {
 	c.JSON(http.StatusOK, cron)
 }
 
-// GetCronList gets the cron job list from the database and writes
-// to the response in json format.
+// GetCronList
+//
+//	@Summary	Get the cron job list
+//	@Router		/repos/{owner}/{name}/cron [get]
+//	@Produce	json
+//	@Success	200	{array}	Cron
+//	@Tags		Repository cron jobs
+//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		owner			path	string	true	"the repository owner's name"
+//	@Param		name			path	string	true	"the repository name"
+//	@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)
 func GetCronList(c *gin.Context) {
 	repo := session.Repo(c)
 	list, err := store.FromContext(c).CronList(repo, session.Pagination(c))
@@ -195,7 +245,17 @@ func GetCronList(c *gin.Context) {
 	c.JSON(http.StatusOK, list)
 }
 
-// DeleteCron deletes the named cron job from the database.
+// DeleteCron
+//
+//	@Summary	Delete a cron job by id
+//	@Router		/repos/{owner}/{name}/cron/{cron} [delete]
+//	@Produce	plain
+//	@Success	200
+//	@Tags		Repository cron jobs
+//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		owner			path	string	true	"the repository owner's name"
+//	@Param		name			path	string	true	"the repository name"
+//	@Param		cron			path	string	true	"the cron job id"
 func DeleteCron(c *gin.Context) {
 	repo := session.Repo(c)
 	id, err := strconv.ParseInt(c.Param("cron"), 10, 64)