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>

.ecrc

@@ -8,6 +8,7 @@
     "node_modules",
     "server/store/datastore/migration/testfiles/sqlite.db",
     "server/store/datastore/feed.go",
+    "cmd/server/docs/docs.go",
     "_test.go",
     "Makefile"
   ]

.gitignore

@@ -40,9 +40,6 @@ extras/
 /build/
 /dist/
 
-server/swagger/files/*.json
-server/swagger/swagger_gen.go
-
 docs/venv
 
 # helm charts
@@ -51,3 +48,4 @@ docs/venv
 
 ### Generated by CI ###
 docs/docs/40-cli.md
+docs/docs/20-usage/90-rest-api.md

.golangci.yml

@@ -40,10 +40,6 @@ run:
 
 issues:
   exclude-rules:
-    - path: woodpecker-go/woodpecker/client.go|server/swagger/swagger.go
-      linters:
-        - deadcode
-        - unused
     # gin force us to use string as context key
     - path: server/store/context.go
       linters:

.woodpecker/test.yml

@@ -45,6 +45,16 @@ pipeline:
     when:
       path: *when_path
 
+  check_swagger:
+    image: *golang_image
+    group: test
+    commands:
+      - "make generate-swagger"
+      - "DIFF=$(git diff | head)"
+      - "[ -n \"$DIFF\" ] && { echo \"swagger not up to date, exec 'make generate-swagger' and commit\"; exit 1; } || true"
+    when:
+      path: *when_path
+
   lint-editorconfig:
     image: mstruebing/editorconfig-checker
     group: test

Makefile

@@ -91,9 +91,12 @@ clean: ## Clean build artifacts
 	@[ "1" != "$(shell docker image ls woodpecker/make:local -a | wc -l)" ] && docker image rm woodpecker/make:local || echo no docker image to clean
 
 .PHONY: generate
-generate: ## Run all code generations
+generate: generate-swagger ## Run all code generations
 	go generate ./...
 
+generate-swagger: install-tools ## Run swagger code generation
+	swag init -g server/api/ -g cmd/server/swagger.go --outputTypes go -output cmd/server/docs
+
 check-xgo: ## Check if xgo is installed
 	@hash xgo > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
 		$(GO) install src.techknowlogick.com/xgo@latest; \
@@ -108,6 +111,9 @@ install-tools: ## Install development tools
 	fi ; \
 	hash gofumpt > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
 		go install mvdan.cc/gofumpt@latest; \
+	fi ; \
+	hash swag > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
+		go install github.com/swaggo/swag/cmd/swag@latest; \
 	fi
 
 ui-dependencies: ## Install UI dependencies
@@ -161,7 +167,7 @@ test: test-agent test-server test-server-datastore test-cli test-lib test-ui ##
 build-ui: ## Build UI
 	(cd web/; pnpm install --frozen-lockfile; pnpm build)
 
-build-server: build-ui ## Build server
+build-server: build-ui generate-swagger ## Build server
 	CGO_ENABLED=${CGO_ENABLED} GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-server github.com/woodpecker-ci/woodpecker/cmd/server
 
 build-agent: ## Build agent
@@ -284,5 +290,6 @@ bundle: bundle-agent bundle-server bundle-cli ## Create all bundles
 .PHONY: docs
 docs: ## Generate docs (currently only for the cli)
 	go generate cmd/cli/app.go
+	go generate cmd/server/swagger.go
 
 endif